Laravel Migration

laravel-migration

When to use

Use this skill when the user asks to create a database migration, add a column, create a table, or modify the schema.

Procedure: Create a migration

1. Read conventions — Check ./agents/ and AGENTS.md for table prefixes, column naming, multi-tenant setup.
2. Generate migration — php artisan make:migration create_xyz_table (or add_column, etc.).
3. Write schema — Follow naming conventions, add indexes for WHERE/JOIN columns, use decimal for money.
4. Verify — Run migration (php artisan migrate), then rollback (php artisan migrate:rollback) to confirm reversibility.

All projects

• Use decimal for money — never float.
• Add indexes for columns used in WHERE clauses and JOINs.
• Match existing column naming patterns in the same table or domain.
• Declare recovery: a reversible down(), or a roll-forward plan in the file (see § The recovery contract below). Silence is the violation.

Laravel projects

Multi-database architecture

Some projects use multiple database connections. Check config/database.php for connections.

Always determine which database the table belongs to before creating a migration.

API database migration

php artisan make:migration create_example_table

return new class extends Migration {
    public function up(): void
    {
        Schema::connection('api_database')->create('example_table', function (Blueprint $table): void {
            $table->id();
            $table->unsignedBigInteger('customer_id');
            $table->string('name');
            $table->boolean('is_active')->default(true);
            $table->timestamps();
            $table->softDeletes();

            $table->foreign('customer_id')
                ->references('id')
                ->on('customers')
                // Choose the referential action; never inherit it from a
                // template. See "Referential action is a decision" below.
                ->onDelete('cascade'); // cascade: rows here are expendable
                                       // WITHOUT their customer

            $table->index('is_active');
        });
    }

    public function down(): void
    {
        Schema::connection('api_database')->dropIfExists('example_table');
    }
};

Customer database migration

php artisan make:migration:customer AddWeatherColumn --table=cl_lv_weather

Customer database tables use the cl_ prefix (e.g. cl_user, cl_lv_weather).

Adding a column (with explicit connection)

return new class extends Migration {
    public function up(): void
    {
        Schema::connection('my_connection')->table('example', function (Blueprint $table): void {
            $table->unsignedInteger('new_column')->after('existing_column');
        });
    }

    public function down(): void
    {
        Schema::connection('my_connection')->table('example', function (Blueprint $table): void {
            $table->dropColumn('new_column');
        });
    }
};

Running migrations

# Default connection
php artisan migrate                           # development
php artisan migrate --env=testing             # testing

# Multi-tenant / custom — check AGENTS.md or module docs for project-specific commands
# Example: php artisan migrate:tenants, php artisan migrate --database=tenant

Composer / legacy projects

• Check where existing migrations live (e.g. core/migrations/).
• Use the existing migration format and naming conventions in the project.

Column conventions

• Foreign keys: {entity}_id (e.g. customer_id, user_id)
• Booleans: is_ prefix (e.g. is_active, is_default)
• Dates: descriptive suffix (e.g. upload_date, deleted_at)
• Always use unsignedBigInteger for foreign keys referencing id() columns
• Use ->after('column') to place new columns logically

Output format

1. Migration file with up() and down() methods
2. Model updates if columns or relationships changed

The recovery contract — one obligation, two branches

Every migration declares one of these, and silence is the violation:

1. a down() that restores the prior state; or
2. a roll-forward recovery plan, written in the migration file itself, for the cases where restoration is genuinely impossible — a completed destructive backfill, a dropped column whose data is gone.

The second branch is not a lighter obligation. A migration taking it records, in its own file comments, all three of:

1. why restoration is impossible, with the evidence — the data was checked and is unrecoverable, not assumed to be;
2. the ordered recovery procedure — the steps, the inputs each needs, and the criteria that say recovery succeeded;
3. the responsible recovery owner.

Vague intent or missing detail is the violation. The plan lives in the migration file and lands in the same diff, because a plan documented "later" somewhere else is a plan nobody can review at the moment it matters.

Referential action is a decision

The template above labels its onDelete('cascade') as one branch, not a default. Copying it unchanged is how a delete of one customer silently removes records that had independent value.

Two consequences worth stating because they are the ones missed:

• restrict is the safe default for anything a finance, audit, or legal reader would expect to still exist. A failed delete is a conversation; a cascaded delete is a recovery.
• set null needs the foreign-key column to be nullable, and it needs the application to handle the orphan state. Choosing it without both is choosing a constraint error later.

Soft deletes do not interact with this: onDelete fires on a real DELETE, so a soft-deleting parent never triggers it. If the model soft-deletes, the referential action describes what happens on a force-delete or a purge, and that is the case to decide against.

Gotcha

• Always check if the table/column already exists before creating the migration — the model doesn't always check.
• Multi-tenant migrations need special handling — customer tables use different prefixes.
• Don't modify existing migrations that have been deployed — create a new migration instead.
• The model forgets ->after('column') for column ordering — MariaDB respects it, and it matters for readability.

Do NOT

• Do NOT create migrations without specifying the correct connection when multiple databases exist.
• Do NOT create tables without checking the project's naming conventions (prefixes, casing).
• Do NOT use raw SQL in migrations when Schema builder works.
• Do NOT leave recovery undeclared — ship a down() that restores the prior state, or the three-part roll-forward plan in the migration file. Neither is optional; choosing between them is.
• Do NOT use float for money — use decimal.
• Do NOT forget indexes on foreign keys and frequently filtered columns.

Adversarial review

Before finalizing a migration, run the adversarial-review skill. Focus on the "Database migrations" attack questions: Can this destroy data? Is rollback possible?

Auto-trigger keywords

• database migration
• create migration
• table prefix
• column naming
• add column
• create table