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
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 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:
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:
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 tocategories.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_centsis 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:
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:
php artisan migrate --pretend 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:
php artisan migrate 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 DONECheck the result with php artisan db:table books:
Foreign Key .......................................... On Update / On Delete
category_id references id on categories ................ no action / cascadeRolling back and redoing
php artisan migrate:rollback 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 DONEAll 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:statusshows each file and whether it ran.migrate:freshdrops all tables and re-runs every migration;--seedadds the seeders. It is wonderful in development and dangerous anywhere else.migrate:rollback --step=1undoes 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:freshon a database with data you need. It drops everything. - Foreign key columns that do not match the parent's type. Use
foreignIdandconstrained. - 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
php artisan make:migration add_subtitle_to_books_table --table=bookspublic 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');
});
}php artisan migrate
php artisan db:table books
php artisan migrate:rollback --step=1The 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.