Laravel Migrations¶

Migrations are version control for the database schema. Each migration is a PHP class that creates, modifies, or drops tables and columns. Migrations run in order and can be rolled back. They work with [[laravel-eloquent-orm]] models and support foreign key constraints for relationships.

Key Facts¶

Migrations live in database/migrations/ with timestamped filenames
php artisan make:migration create_posts_table generates a migration class
php artisan make:model Post -m creates model + migration together
up() method applies changes; down() method reverses them
php artisan migrate runs all pending migrations
php artisan migrate:rollback undoes the last batch
php artisan migrate:fresh drops all tables and re-runs all migrations (destructive)
Foreign keys enforce referential integrity between tables
$table->softDeletes() adds deleted_at column for [[laravel-eloquent-orm]] soft deletes
Default migrations create users, password_reset_tokens, sessions, cache, jobs tables
SQLite is the default database in Laravel 11; switch to MySQL/MariaDB via .env

Patterns¶

Creating a table¶

<?php
use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration
{
    public function up(): void
    {
        Schema::create('posts', function (Blueprint $table) {
            $table->id();                          // bigint unsigned auto-increment PK
            $table->string('title');                // varchar(255)
            $table->string('slug')->unique();       // unique index
            $table->text('body');                   // text
            $table->string('image')->nullable();    // nullable varchar
            $table->boolean('is_published')->default(false);
            $table->foreignId('category_id')        // bigint unsigned
                  ->constrained()                   // foreign key to categories.id
                  ->onDelete('cascade');             // delete posts when category deleted
            $table->foreignId('user_id')
                  ->constrained();
            $table->softDeletes();                  // deleted_at timestamp
            $table->timestamps();                   // created_at, updated_at
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('posts');
    }
};

Many-to-many pivot table¶

<?php
// Pivot table for Post <-> Tag (many-to-many)
// Naming convention: alphabetical order, singular - post_tag
return new class extends Migration
{
    public function up(): void
    {
        Schema::create('post_tag', function (Blueprint $table) {
            $table->id();
            $table->foreignId('post_id')->constrained()->onDelete('cascade');
            $table->foreignId('tag_id')->constrained()->onDelete('cascade');
            $table->timestamps();

            // Prevent duplicate assignments
            $table->unique(['post_id', 'tag_id']);
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('post_tag');
    }
};

Modifying existing tables¶

<?php
// Add column to existing table
return new class extends Migration
{
    public function up(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->tinyInteger('role')->default(0)->after('email');
        });
    }

    public function down(): void
    {
        Schema::table('users', function (Blueprint $table) {
            $table->dropColumn('role');
        });
    }
};

Column types reference¶

<?php
Schema::create('example', function (Blueprint $table) {
    // Numeric
    $table->id();                      // BIGINT UNSIGNED AUTO_INCREMENT PK
    $table->bigInteger('count');       // BIGINT
    $table->integer('quantity');        // INT
    $table->tinyInteger('role');        // TINYINT (0-255)
    $table->float('price', 8, 2);      // FLOAT
    $table->decimal('amount', 10, 2);  // DECIMAL

    // String
    $table->string('name', 100);       // VARCHAR(100)
    $table->text('body');              // TEXT
    $table->longText('content');       // LONGTEXT

    // Date/Time
    $table->timestamp('published_at'); // TIMESTAMP
    $table->date('birth_date');        // DATE
    $table->timestamps();              // created_at + updated_at

    // Boolean
    $table->boolean('is_active');      // TINYINT(1)

    // JSON
    $table->json('meta');              // JSON

    // Modifiers
    $table->string('avatar')->nullable();        // allows NULL
    $table->integer('sort')->default(0);          // default value
    $table->string('email')->unique();            // unique index
    $table->integer('position')->unsigned();      // unsigned
    $table->softDeletes();                         // deleted_at nullable timestamp
    $table->string('bio')->after('name');          // column position (MySQL)
});

Artisan migration commands¶

# Generate migration
php artisan make:migration create_posts_table
php artisan make:migration add_role_to_users_table

# Run migrations
php artisan migrate              # execute pending
php artisan migrate --seed       # migrate + seed

# Rollback
php artisan migrate:rollback     # undo last batch
php artisan migrate:rollback --step=2  # undo last 2 batches
php artisan migrate:reset        # undo all migrations

# Fresh start (drops all tables)
php artisan migrate:fresh        # drop all + re-migrate
php artisan migrate:fresh --seed # drop all + re-migrate + seed

# Status
php artisan migrate:status       # show migration status

Gotchas¶

Symptom	Cause	Fix
Foreign key constraint error	Referenced table doesn't exist yet	Ensure referenced table migration runs first (earlier timestamp)
`Cannot delete parent row`	Child records exist with foreign key	Use `onDelete('cascade')` or delete children first
`Column already exists`	Migration ran partially or was modified after running	Run `migrate:fresh` in development; create new migration in production
Default SQLite can't handle some features	SQLite lacks `ALTER TABLE DROP COLUMN` (older versions)	Switch to MySQL in `.env` for full feature support
Adding column to existing table fails	Using `Schema::create` instead of `Schema::table`	Use `Schema::table()` for modifications
Rollback doesn't undo changes	`down()` method not implemented	Always implement `down()` that reverses `up()`