README

Simple, explicit database migrations for WordPress via WP-CLI.

korvir/wp-migrations is a lightweight migration system inspired by Laravel, but focused on WordPress + MySQL/MariaDB.

Requirements

• PHP 7.4+
• WordPress 5.5+
• MySQL/MariaDB
• WP-CLI

Install

composer require korvir/wp-migrations

Quick Start

Create a migration:

wp migrations add create_users_table

Run pending migrations:

wp migrations migrate

Check status:

wp migrations status

Rollback last batch:

wp migrations rollback

Commands

Command Options

add

• --path=<path>: custom migrations path.

migrate

• [<name>]: run one specific migration.
• --only=<names>: comma-separated filename fragments to include.
• --except=<names>: comma-separated filename fragments to exclude.
• --step=<N>: run only next N pending migrations.
• --path=<path>: custom migrations path.
• --pretend: dry-run (print migrations without executing).
• --force: skip production confirmation.

rollback

• --step=<N>: rollback N latest executed migrations (ignores batch boundary).
• --pretend: dry-run.

reset

• --path=<path>
• --pretend

fresh

• --path=<path>
• --pretend

Notes:

• --only and --except are mutually exclusive.
• In production environment, migrate asks for confirmation unless --force is provided.

Migration File Structure

Use MigrationInterface:

<?php

use WPMigrations\Migrations\MigrationInterface;
use WPMigrations\Schema\Blueprint;
use WPMigrations\Schema\Schema;

return new class implements MigrationInterface
{
    public function up(): void {
        Schema::create('users', function (Blueprint $table) {
            $table->id();
            $table->string('email', 190);
            $table->timestamps();
        });
    }

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

Schema API

Schema methods

Schema::create();
Schema::table();
Schema::rename();
Schema::drop();
Schema::dropIfExists();
Schema::hasTable();
Schema::hasColumn();
Schema::hasIndex();
Schema::createView();
Schema::dropView();
Schema::createOrReplaceView();
Schema::raw();

Column Types (Blueprint)

Column Modifiers

Indexes

Foreign Keys

• foreign($column)->references()->on()->onDelete()->onUpdate()->name()
• dropForeign($name)
• foreignId($column)->constrained($table = null, $column = 'id')
• foreignId(...)->cascadeOnDelete()/cascadeOnUpdate()/restrictOnDelete()/nullOnDelete()
• dropConstrainedForeignId($column)

Views

Schema::createOrReplaceView(
    'active_users',
    "SELECT id, email FROM wp_users WHERE user_status = 0"
);

Schema::dropView('active_users');

Raw SQL

Schema::raw('ALTER TABLE wp_users ENGINE=InnoDB');

Schema::raw([
    'SET FOREIGN_KEY_CHECKS=0',
    'DROP TABLE IF EXISTS wp_legacy',
    'SET FOREIGN_KEY_CHECKS=1',
]);

Stub Resolution

wp migrations add selects a stub by migration prefix:

• create_* -> create.stub.php
• update_* -> update.stub.php
• rename_* -> rename.stub.php
• drop_* -> drop.stub.php
• otherwise -> default.stub.php

Stub lookup order:

1. WP_MIGRATIONS_STUB_PATH
2. <theme>/migrations/stubs
3. package stubs/

Publish stubs into project:

wp migrations stub:publish

Configuration

Path resolution order for migrations:

1. CLI option --path
2. WP_MIGRATIONS_PATH
3. <theme>/migrations
4. WP_CONTENT_DIR/migrations

Programmatic runner config:

new WPMigrations\Migrations\MigrationRunner([
    'path' => '/custom/migrations/path',
    'table' => 'wp_migrations',
    // 'strict' => true,
    // 'connection' => custom ConnectionInterface implementation,
]);

Important Notes

• Execution is explicit; there is no schema introspection.
• Rollback is not transaction-wrapped by default.
• Write defensive down() methods (especially for FK/index/column order).
• For MySQL, drop foreign keys before dropping dependent indexes/columns.
• Multisite is not first-class; if you iterate blogs manually, rollback correctness is on migration author.