Laravel Migrations Explained — Structure, Rollbacks & Real-World Patterns

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

// Each migration is a class that extends Migration.
// Laravel auto-discovers it — no registration needed.
return new class extends Migration
{
    /**
     * Run the migration — this is what `php artisan migrate` executes.
     * Build the table exactly as your application needs it right now.
     */
    public function up(): void
    {
        Schema::create('articles', function (Blueprint $table) {
            $table->id();                          // Unsigned BIGINT primary key, auto-increment
            $table->string('title', 200);          // VARCHAR(200) — cap it, don't leave it unbounded
            $table->string('slug', 200)->unique(); // Unique index created automatically by ->unique()
            $table->text('body');                  // TEXT column — no length limit
            $table->boolean('is_published')->default(false); // Sensible default — articles start as drafts
            $table->timestamp('published_at')->nullable();   // NULL until the article goes live
            $table->timestamps();                  // Adds created_at and updated_at (both nullable TIMESTAMP)
        });
    }

    /**
     * Reverse the migration — this is what `php artisan migrate:rollback` executes.
     * dropIfExists prevents an error if someone manually dropped the table already.
     */
    public function down(): void
    {
        Schema::dropIfExists('articles');
    }
};

<?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
    {
        // --- Creating a table with a foreign key relationship ---
        Schema::create('comments', function (Blueprint $table) {
            $table->id();

            // foreignId() creates an UNSIGNED BIGINT column named 'article_id'
            // constrained() adds the actual FK constraint pointing to articles.id
            // cascadeOnDelete() means: if the article is deleted, delete its comments too
            $table->foreignId('article_id')
                  ->constrained()
                  ->cascadeOnDelete();

            // Same pattern for the user who wrote the comment
            $table->foreignId('user_id')
                  ->constrained()
                  ->cascadeOnDelete();

            $table->text('body');

            // Composite index: we almost always query comments BY article, ordered by date
            // A composite index on (article_id, created_at) makes that query fast
            $table->index(['article_id', 'created_at'], 'comments_article_date_index');

            $table->timestamps();
            $table->softDeletes(); // Adds deleted_at TIMESTAMP NULL — enables Eloquent soft deletes
        });
    }

    public function down(): void
    {
        // Foreign key constraints must be dropped BEFORE the table that holds them
        // dropIfExists handles both the FK constraints and the table in the correct order
        Schema::dropIfExists('comments');
    }
};

// ----------------------------------------------------------------
// SEPARATE FILE: Adding a column to an EXISTING table
// ----------------------------------------------------------------
// 2024_02_10_000001_add_excerpt_to_articles_table.php

return new class extends Migration
{
    public function up(): void
    {
        Schema::table('articles', function (Blueprint $table) {
            // ->after() places the column right after 'title' in the column order
            // This is MySQL-only — it's cosmetic but makes DESCRIBE output readable
            $table->string('excerpt', 500)
                  ->nullable()          // Existing rows have no excerpt — nullable prevents errors
                  ->after('title');     // Column ordering hint for readability
        });
    }

    public function down(): void
    {
        Schema::table('articles', function (Blueprint $table) {
            // Always drop the column in down() — make rollback a clean undo
            $table->dropColumn('excerpt');
        });
    }
};

<?php

// database/seeders/DatabaseSeeder.php
// Seeders fill your freshly migrated database with realistic test data.
// They pair with migrations to give you a reproducible, usable dev environment.

namespace Database\Seeders;

use App\Models\Article;
use App\Models\Comment;
use App\Models\User;
use Illuminate\Database\Seeder;

class DatabaseSeeder extends Seeder
{
    public function run(): void
    {
        // Create 5 users using the User factory (defined in database/factories/)
        $users = User::factory(5)->create();

        // Create 20 articles, each assigned to a random one of those 5 users
        $articles = Article::factory(20)
            ->recycle($users)   // Reuse existing users rather than creating new ones
            ->create();

        // Create 3–8 comments per article, each from a random user
        $articles->each(function (Article $article) use ($users) {
            Comment::factory(
                rand(3, 8)   // Realistic variation — not every article has the same engagement
            )
            ->recycle($users)
            ->for($article)
            ->create();
        });

        // Report to the console so you can see the seeder is working
        $this->command->info('Database seeded with 5 users, 20 articles, and their comments.');
    }
}

/*
 * USEFUL COMMANDS:
 *
 * php artisan migrate:fresh --seed
 *   Drops all tables, re-runs all migrations, then runs DatabaseSeeder.
 *   Use this at the start of each dev session for a clean slate.
 *
 * php artisan migrate:refresh --seed
 *   Same result, but uses your down() methods — tests rollback logic too.
 *
 * php artisan migrate --pretend
 *   Prints the SQL that WOULD run. Great for reviewing before production deploys.
 */

<?php

/**
 * ZERO-DOWNTIME MIGRATION PATTERN
 *
 * Scenario: You need to add a NOT NULL 'reading_time_minutes' column to a table
 * that already has 50,000 rows in production.
 *
 * Naive approach (DANGEROUS on live traffic):
 *   $table->integer('reading_time_minutes'); // Locks the table while backfilling NULL values!
 *
 * Safe 3-step approach below:
 */

// ── STEP 1: Add the column as NULLABLE (no lock, instant) ────────────────────
// 2024_03_01_000001_add_reading_time_to_articles_nullable.php
return new class extends Migration
{
    public function up(): void
    {
        Schema::table('articles', function (Blueprint $table) {
            // Nullable = existing rows get NULL immediately, no table scan needed
            $table->integer('reading_time_minutes')->nullable()->after('body');
        });
    }

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

// ── STEP 2: Backfill existing rows in a queued job (NOT in a migration) ───────
// app/Jobs/BackfillArticleReadingTime.php
//
// class BackfillArticleReadingTime implements ShouldQueue
// {
//     public function handle(): void
//     {
//         Article::whereNull('reading_time_minutes')
//             ->chunkById(500, function ($articles) {
//                 foreach ($articles as $article) {
//                     $wordCount = str_word_count(strip_tags($article->body));
//                     $article->update([
//                         'reading_time_minutes' => (int) ceil($wordCount / 200)
//                     ]);
//                 }
//             });
//     }
// }
//
// Dispatch this job AFTER Step 1 deploys. Let it run in the background.

// ── STEP 3: Add the NOT NULL constraint once all rows are backfilled ──────────
// 2024_03_05_000001_make_reading_time_not_nullable_on_articles.php
return new class extends Migration
{
    public function up(): void
    {
        Schema::table('articles', function (Blueprint $table) {
            // By now every row has a value. Safe to add constraint.
            $table->integer('reading_time_minutes')
                  ->default(1)       // Fallback for any edge cases missed by the backfill
                  ->nullable(false)  // Remove the nullable flag — adds NOT NULL constraint
                  ->change();        // ->change() tells Laravel to ALTER the existing column
        });
    }

    public function down(): void
    {
        Schema::table('articles', function (Blueprint $table) {
            $table->integer('reading_time_minutes')->nullable()->change();
        });
    }
};