Laravel Migrations
Agent Workflow (MANDATORY)
Before ANY implementation, spawn 3 agents in parallel, one Agent call each with a name:
- fuse-ai-pilot:explore-codebase - Check existing migrations
- fuse-ai-pilot:research-expert - Verify Laravel 13 patterns via Context7
- mcp__context7__query-docs - Check specific Schema Builder features
After implementation, run fuse-ai-pilot:sniper for validation.
Overview
| Feature |
Description |
| Schema Builder |
Create, modify, drop tables |
| Columns |
50+ column types with modifiers |
| Indexes |
Primary, unique, fulltext, spatial |
| Foreign Keys |
Constraints with cascade options |
| Seeders |
Populate tables with data |
Critical Rules
- Always define down() - Reversible migrations
- Use foreignId()->constrained() - Not raw unsignedBigInteger
- Add indexes on foreign keys - Performance critical
- Test rollback before deploy - Validate down() works
- Never modify deployed migrations - Create new ones
Decision Guide
Migration Type
Need schema change?
├── New table → make:migration create_X_table
├── Add column → make:migration add_X_to_Y_table
├── Modify column → make:migration modify_X_in_Y_table
├── Add index → make:migration add_index_to_Y_table
└── Seed data → make:seeder XSeeder
Column Type Selection
| Use Case |
Type |
Example |
| Primary Key |
id() |
Auto-increment BIGINT |
| Foreign Key |
foreignId()->constrained() |
References parent |
| UUID Primary |
uuid()->primary() |
UUIDs |
| Boolean |
boolean() |
is_active |
| Enum |
enum('status', [...]) |
order_status |
| JSON |
json() |
preferences |
| Money |
decimal('price', 10, 2) |
99999999.99 |
| Timestamps |
timestamps() |
created_at, updated_at |
| Soft Delete |
softDeletes() |
deleted_at |
Foreign Key Cascade
| Scenario |
onDelete |
Use Case |
| Strict integrity |
restrictOnDelete() |
Financial records |
| Auto-cleanup |
cascadeOnDelete() |
Post → Comments |
| Preserve with null |
nullOnDelete() |
Optional relations |
| No action |
noActionOnDelete() |
Audit logs |
Reference Guide
Core Concepts
| Topic |
Reference |
When to Consult |
| Schema |
schema.md |
Table operations |
| Columns |
columns.md |
Column types |
| Indexes |
indexes.md |
Performance indexes |
| Foreign Keys |
foreign-keys.md |
Constraints |
| Commands |
commands.md |
Artisan commands |
| Seeding |
seeding.md |
Populate data |
Advanced Topics
| Topic |
Reference |
When to Consult |
| Testing |
testing.md |
Test migrations |
| Production |
production.md |
Deploy safely |
| Troubleshooting |
troubleshooting.md |
Fix errors |
Templates
| Template |
When to Use |
| CreateTableMigration.php.md |
New table |
| ModifyTableMigration.php.md |
Alter table |
| PivotTableMigration.php.md |
Many-to-many |
| Seeder.php.md |
Seed patterns |
| MigrationTest.php.md |
Test migrations |
Quick Reference
Create Table
Schema::create('posts', function (Blueprint $table) {
$table->id();
$table->foreignId('user_id')->constrained()->cascadeOnDelete();
$table->string('title');
$table->text('content');
$table->enum('status', ['draft', 'published'])->default('draft');
$table->timestamps();
$table->softDeletes();
$table->index(['user_id', 'status']);
});
Modify Table
Schema::table('posts', function (Blueprint $table) {
$table->string('slug')->after('title')->unique();
$table->boolean('featured')->default(false);
});
Commands
php artisan make:migration create_posts_table
php artisan migrate
php artisan migrate:rollback --step=1
php artisan migrate:fresh --seed
Best Practices
DO
- Use
foreignId()->constrained() for foreign keys
- Add composite indexes for common queries
- Test down() method before deploying
- Use
--pretend to preview SQL
DON'T
- Modify already-deployed migrations
- Forget down() method
- Use raw SQL without Schema Builder
- Skip indexes on foreign keys
Laravel 13 Notes
Schema::ensureVectorExtensionExists() (pgvector)
Laravel 13 expose une helper pour activer l'extension pgvector sur PostgreSQL depuis une migration. Utile pour embeddings et recherche sémantique.
use Illuminate\Support\Facades\Schema;
return new class extends Migration {
public function up(): void
{
Schema::ensureVectorExtensionExists();
Schema::create('documents', function (Blueprint $table) {
$table->id();
$table->text('content');
$table->vector('embedding', dimensions: 1536); // OpenAI ada-002
$table->timestamps();
$table->index('embedding', 'documents_embedding_idx', 'hnsw');
});
}
};
Voir [[laravel-vector-search]] pour les requêtes whereVectorSimilarTo().
1---2name: laravel-migrations3description: Use when designing a database schema or managing Laravel 13 migrations — Schema Builder, columns, indexes, foreign keys, or seeders.4versions:5 laravel: "13.0"6 php: "8.3"7user-invocable: true8references: references/schema.md, references/columns.md, references/indexes.md, references/foreign-keys.md, references/commands.md, references/seeding.md, references/testing.md, references/production.md, references/troubleshooting.md, references/templates/CreateTableMigration.php.md, references/templates/ModifyTableMigration.php.md, references/templates/PivotTableMigration.php.md, references/templates/Seeder.php.md, references/templates/MigrationTest.php.md9related-skills: laravel-eloquent, laravel-testing, laravel-architecture10metadata:11 source: https://skillmd.com/skills/fusengine/laravel-migrations12---1314<objective>15Covers Laravel 13 database migrations: the Schema Builder API for16creating/modifying/dropping tables, the 50+ column types and modifiers,17index types (primary, unique, fulltext, spatial), foreign key constraints18with cascade options, Artisan migration commands, seeders, testing19migrations, safe production rollout, troubleshooting, and enabling pgvector20via Schema::ensureVectorExtensionExists() for vector columns (see21laravel-vector-search for querying them).22</objective>2324# Laravel Migrations2526## Agent Workflow (MANDATORY)2728Before ANY implementation, spawn 3 agents in parallel, one `Agent` call each with a `name`:29301. **fuse-ai-pilot:explore-codebase** - Check existing migrations312. **fuse-ai-pilot:research-expert** - Verify Laravel 13 patterns via Context7323. **mcp__context7__query-docs** - Check specific Schema Builder features3334After implementation, run **fuse-ai-pilot:sniper** for validation.3536---3738## Overview3940| Feature | Description |41|---------|-------------|42| **Schema Builder** | Create, modify, drop tables |43| **Columns** | 50+ column types with modifiers |44| **Indexes** | Primary, unique, fulltext, spatial |45| **Foreign Keys** | Constraints with cascade options |46| **Seeders** | Populate tables with data |4748---4950## Critical Rules51521. **Always define down()** - Reversible migrations532. **Use foreignId()->constrained()** - Not raw unsignedBigInteger543. **Add indexes on foreign keys** - Performance critical554. **Test rollback before deploy** - Validate down() works565. **Never modify deployed migrations** - Create new ones5758---5960## Decision Guide6162### Migration Type6364```65Need schema change?66├── New table → make:migration create_X_table67├── Add column → make:migration add_X_to_Y_table68├── Modify column → make:migration modify_X_in_Y_table69├── Add index → make:migration add_index_to_Y_table70└── Seed data → make:seeder XSeeder71```7273### Column Type Selection7475| Use Case | Type | Example |76|----------|------|---------|77| Primary Key | `id()` | Auto-increment BIGINT |78| Foreign Key | `foreignId()->constrained()` | References parent |79| UUID Primary | `uuid()->primary()` | UUIDs |80| Boolean | `boolean()` | is_active |81| Enum | `enum('status', [...])` | order_status |82| JSON | `json()` | preferences |83| Money | `decimal('price', 10, 2)` | 99999999.99 |84| Timestamps | `timestamps()` | created_at, updated_at |85| Soft Delete | `softDeletes()` | deleted_at |8687### Foreign Key Cascade8889| Scenario | onDelete | Use Case |90|----------|----------|----------|91| Strict integrity | `restrictOnDelete()` | Financial records |92| Auto-cleanup | `cascadeOnDelete()` | Post → Comments |93| Preserve with null | `nullOnDelete()` | Optional relations |94| No action | `noActionOnDelete()` | Audit logs |9596---9798## Reference Guide99100### Core Concepts101102| Topic | Reference | When to Consult |103|-------|-----------|-----------------|104| **Schema** | [schema.md](references/schema.md) | Table operations |105| **Columns** | [columns.md](references/columns.md) | Column types |106| **Indexes** | [indexes.md](references/indexes.md) | Performance indexes |107| **Foreign Keys** | [foreign-keys.md](references/foreign-keys.md) | Constraints |108| **Commands** | [commands.md](references/commands.md) | Artisan commands |109| **Seeding** | [seeding.md](references/seeding.md) | Populate data |110111### Advanced Topics112113| Topic | Reference | When to Consult |114|-------|-----------|-----------------|115| **Testing** | [testing.md](references/testing.md) | Test migrations |116| **Production** | [production.md](references/production.md) | Deploy safely |117| **Troubleshooting** | [troubleshooting.md](references/troubleshooting.md) | Fix errors |118119### Templates120121| Template | When to Use |122|----------|-------------|123| [CreateTableMigration.php.md](references/templates/CreateTableMigration.php.md) | New table |124| [ModifyTableMigration.php.md](references/templates/ModifyTableMigration.php.md) | Alter table |125| [PivotTableMigration.php.md](references/templates/PivotTableMigration.php.md) | Many-to-many |126| [Seeder.php.md](references/templates/Seeder.php.md) | Seed patterns |127| [MigrationTest.php.md](references/templates/MigrationTest.php.md) | Test migrations |128129---130131## Quick Reference132133### Create Table134135```php136Schema::create('posts', function (Blueprint $table) {137 $table->id();138 $table->foreignId('user_id')->constrained()->cascadeOnDelete();139 $table->string('title');140 $table->text('content');141 $table->enum('status', ['draft', 'published'])->default('draft');142 $table->timestamps();143 $table->softDeletes();144145 $table->index(['user_id', 'status']);146});147```148149### Modify Table150151```php152Schema::table('posts', function (Blueprint $table) {153 $table->string('slug')->after('title')->unique();154 $table->boolean('featured')->default(false);155});156```157158### Commands159160```bash161php artisan make:migration create_posts_table162php artisan migrate163php artisan migrate:rollback --step=1164php artisan migrate:fresh --seed165```166167---168169## Best Practices170171### DO172- Use `foreignId()->constrained()` for foreign keys173- Add composite indexes for common queries174- Test down() method before deploying175- Use `--pretend` to preview SQL176177### DON'T178- Modify already-deployed migrations179- Forget down() method180- Use raw SQL without Schema Builder181- Skip indexes on foreign keys182183---184185## Laravel 13 Notes186187### Schema::ensureVectorExtensionExists() (pgvector)188Laravel 13 expose une helper pour activer l'extension `pgvector` sur PostgreSQL depuis une migration. Utile pour embeddings et recherche sémantique.189190```php191use Illuminate\Support\Facades\Schema;192193return new class extends Migration {194 public function up(): void195 {196 Schema::ensureVectorExtensionExists();197198 Schema::create('documents', function (Blueprint $table) {199 $table->id();200 $table->text('content');201 $table->vector('embedding', dimensions: 1536); // OpenAI ada-002202 $table->timestamps();203204 $table->index('embedding', 'documents_embedding_idx', 'hnsw');205 });206 }207};208```209210Voir [[laravel-vector-search]] pour les requêtes `whereVectorSimilarTo()`.