Himanshu SharmaSoftware engineer
Let’s talk

Laravel · Lesson 16 of 40

Laravel migrations

Create database tables with migration files, use the schema builder for columns and foreign keys, and run, preview and roll back migrations with real output.

14 minDatabase and migrationsUpdated 14 November 2026

Awaiting technical review. This lesson is readable but not yet listed in search engines.

By the end of this lessonWrite migrations for the categories and books tables and an is_admin column, run and roll them back, and explain why changes go in new files rather than editing old ones.

What you can do after this lesson

You will create Pagelane Books' first real tables, categories and books, and add an is_admin flag to users, all with code you can run on any machine. You will also know how to undo and redo a change safely.

Why migrations

If you create tables by hand in a database tool, nobody else (including you next month, on a server) can reproduce them. A migration describes a database change in PHP. Files live in database/migrations, and their timestamp prefix sets the order. Laravel records which have run in a table named migrations, so each runs once. Teammates pull the code, run php artisan migrate, and get the same structure. You saw this already: a fresh project ships with three migrations.

Creating migrations

bash
php artisan make:migration create_categories_table
php artisan make:migration create_books_table
php artisan make:migration add_is_admin_to_users_table --table=users
text
   INFO  Migration [database/migrations/2026_11_15_074424_create_categories_table.php] created successfully.
   INFO  Migration [database/migrations/2026_11_15_074425_create_books_table.php] created successfully.
   INFO  Migration [database/migrations/2026_11_15_074426_add_is_admin_to_users_table.php] created successfully.

(The timestamps in your file names will differ; they are the moment you ran the command.) Laravel guesses from the name: create_..._table generates a Schema::create stub. The --table option tells it to alter an existing table. A migration file returns an anonymous class with two methods. Here is the categories one, after filling the columns:

php
return new class extends Migration
{
    public function up(): void
    {
        Schema::create('categories', function (Blueprint $table) {
            $table->id();
            $table->string('name')->unique();
            $table->string('slug')->unique();
            $table->timestamps();
        });
    }

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

id() makes an auto-incrementing primary key. string is a short text (varchar), unique() adds a unique index, and timestamps() adds created_at and updated_at, which Eloquent fills in for you. The books table:

php
Schema::create('books', function (Blueprint $table) {
    $table->id();
    $table->foreignId('category_id')->constrained()->cascadeOnDelete();
    $table->string('title');
    $table->string('author');
    $table->string('isbn', 13)->unique();
    $table->text('description')->nullable();
    $table->unsignedInteger('price_cents');
    $table->date('published_on')->nullable();
    $table->string('cover_path')->nullable();
    $table->timestamps();
});

Notes:

  • foreignId('category_id')->constrained() makes an unsigned big integer column and a foreign key to categories.id, inferring the table name from the column name. cascadeOnDelete() deletes a category's books when the category is deleted; for real shops you might prefer to block that deletion.
  • nullable() allows empty values; columns are required by default.
  • price_cents is an integer, matching how the controller stored prices earlier.
  • string('isbn', 13) limits the length to 13 characters. We store it as text because ISBNs can start with zero.

The users change adds one column:

php
Schema::table('users', function (Blueprint $table) {
    $table->boolean('is_admin')->default(false)->after('password');
});

Its down() calls $table->dropColumn('is_admin'). Always write down() correctly so you can go back.

Previewing, running and checking

Before running, you can see the exact SQL:

bash
php artisan migrate --pretend
text
  2026_11_15_074425_create_books_table .......................................
  ⇂ create table "books" ("id" integer primary key autoincrement not null, "category_id" integer not null, "title" varchar not null, "author" varchar not null, "isbn" varchar not null, "description" text, "price_cents" integer not null, "published_on" date, "cover_path" varchar, "created_at" datetime, "updated_at" datetime, foreign key("category_id") references "categories"("id") on delete cascade)

(Shown for one migration; this is SQLite's dialect.) Now run them:

bash
php artisan migrate
text
   INFO  Running migrations.

  2026_11_15_074424_create_categories_table ...................... 4.20ms DONE
  2026_11_15_074425_create_books_table ........................... 4.28ms DONE
  2026_11_15_074426_add_is_admin_to_users_table .................. 0.75ms DONE

Check the result with php artisan db:table books:

text
  Foreign Key .......................................... On Update / On Delete
  category_id references id on categories ................ no action / cascade

Rolling back and redoing

bash
php artisan migrate:rollback
text
   INFO  Rolling back migrations.

  2026_11_15_074426_add_is_admin_to_users_table .................. 4.13ms DONE
  2026_11_15_074425_create_books_table ........................... 0.58ms DONE
  2026_11_15_074424_create_categories_table ...................... 0.63ms DONE

All three were undone because they ran together in one batch. Rollback undoes the last batch, in reverse order, by calling each down(). Running php artisan migrate again re-applies them. Other useful commands, all listed by php artisan list migrate:

  • migrate:status shows each file and whether it ran.
  • migrate:fresh drops all tables and re-runs every migration; --seed adds the seeders. It is wonderful in development and dangerous anywhere else.
  • migrate:rollback --step=1 undoes just one migration.

The one big rule

Once a migration has run on a database that is not only yours (a teammate, a staging server, production), do not edit it. Add a new migration that changes the table. Editing history makes databases diverge, and Laravel will not re-run an already recorded file. While you work alone on a local database, rolling back, editing and re-running is fine.

SQLite has some limits for altering tables, and each database has its own column types. Always run migrations on the database type you will deploy.

Common mistakes

  • Editing an old migration after sharing it. Create a new one.
  • Writing an empty or wrong down(). Rollbacks then fail or leave junk.
  • Using migrate:fresh on a database with data you need. It drops everything.
  • Foreign key columns that do not match the parent's type. Use foreignId and constrained.
  • Forgetting nullable() on optional columns, which then reject inserts with missing values.

Exercise

Write a migration that adds a nullable subtitle string column to books, run it, confirm with db:table, and roll back only that one migration.

Show one possible answer
bash
php artisan make:migration add_subtitle_to_books_table --table=books
php
public function up(): void
{
    Schema::table('books', function (Blueprint $table) {
        $table->string('subtitle')->nullable()->after('title');
    });
}

public function down(): void
{
    Schema::table('books', function (Blueprint $table) {
        $table->dropColumn('subtitle');
    });
}
bash
php artisan migrate
php artisan db:table books
php artisan migrate:rollback --step=1

The table lists subtitle after the migrate and not after the rollback. (This course's later lessons assume you rolled it back.) Next: Eloquent models.

Key points

  • A migration is a PHP file with up() to apply a change and down() to undo it, so database structure is versioned alongside your code.
  • php artisan make:migration creates a timestamped file; migrate runs pending ones, and Laravel records them in the migrations table.
  • The Schema builder offers column types such as string, text, integer, date and boolean, with modifiers like nullable, default and unique.
  • foreignId()->constrained() creates a foreign key to the matching table, and cascadeOnDelete controls what happens to child rows.
  • migrate:rollback undoes the last batch, which can be several files; never edit a migration that others have already run.

Check yourself

1. What are the two methods in a migration class?
2. What does php artisan migrate --pretend do?
3. You already deployed a migration and now need another column. What is the right move?
4. What does foreignId('category_id')->constrained() create?