Laravel Migrations

Agent Workflow (MANDATORY)

Before ANY implementation, use TeamCreate to spawn 3 agents:

• fuse-ai-pilot:explore-codebase - Check existing migrations

• fuse-ai-pilot:research-expert - Verify Laravel 12 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