Creating and Running Laravel Migrations

Acorn brings Laravel's powerful migration system to WordPress, allowing you to version control your database schema and manage custom tables with ease. Each migration contains instructions for creating or modifying database tables.

We recommend referencing the Laravel docs on Database Migrations for a complete understanding of the migration system.

Creating your first migration #

To create a new migration, use the make:migration command:

$ wp acorn make:migration create_app_settings_table

This will create a new migration file in database/migrations/ with a timestamp prefix, like 2025_08_06_140000_create_app_settings_table.php.

Migration file structure #

A typical migration contains two methods:

• up() - Defines changes to apply
• down() - Defines how to reverse those changes

Here's an example migration for an app settings table:

<?php

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

return new class extends Migration
{
    /**
     * Run the migrations.
     */
    public function up(): void
    {
        Schema::create('app_settings', function (Blueprint $table) {
            $table->id();
            $table->string('key')->unique();
            $table->json('value')->nullable();
            $table->string('group')->default('general');
            $table->boolean('is_public')->default(false);
            $table->text('description')->nullable();
            $table->timestamps();
            
            $table->index('group');
            $table->index('is_public');
        });
    }

    /**
     * Reverse the migrations.
     */
    public function down(): void
    {
        Schema::dropIfExists('app_settings');
    }
};

Running migrations #

To run all pending migrations:

$ wp acorn migrate

To see the status of your migrations:

$ wp acorn migrate:status

To rollback the last batch of migrations:

$ wp acorn migrate:rollback

Adding columns to existing tables #

To add columns to an existing table, create a new migration:

$ wp acorn make:migration add_encrypted_to_app_settings_table

public function up(): void
{
    Schema::table('app_settings', function (Blueprint $table) {
        $table->boolean('is_encrypted')->default(false)->after('is_public');
    });
}

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

Deployment #

You should run migrations as part of your deployment process. Add this to your deployment script after wp acorn optimize:

$ wp acorn optimize
$ wp acorn migrate --force

The --force flag runs migrations without confirmation prompts in production environments.

Troubleshooting #

If you get an error about the migrations table not existing, run:

$ wp acorn migrate:install