README

Schema migration runner with a CLI interface for the Meritum ecosystem.

Requirements

• PHP 8.4+
• georgeff/kernel ^1.6
• georgeff/database ^1.0
• georgeff/schema ^1.1
• meritum/cli ^1.0

Installation

composer require meritum/migrations

Configuration

All configuration is provided via environment variables. Source them before invoking strata or set them in your deployment environment.

Variable	Default	Description
DB_DRIVER	pgsql	Database driver — pgsql, mysql, or sqlite
DB_HOST	localhost	Database host
DB_PORT	5432	Database port
DB_DATABASE	(empty)	Database name
DB_USERNAME	(empty)	Database username
DB_PASSWORD	(empty)	Database password
DB_PGSQL_SCHEMA	public	PostgreSQL schema
DB_PGSQL_SSL_MODE	prefer	PostgreSQL SSL mode
DB_MYSQL_CHARSET	utf8mb4	MySQL charset
DB_MIGRATIONS_TABLE	migrations	Table used to track ran migrations
DB_MIGRATIONS_PATH	./migrations	Directory where migration files are stored
APP_ENV	production	Application environment — affects production guards
APP_DEBUG	false	Enable debug mode

The DB_MIGRATIONS_PATH defaults to a migrations/ directory in whichever directory strata is invoked from. Running strata from the project root gives ./migrations without any additional configuration.

Commands

migration:install

Creates the migrations tracking table in the database. Run this once before using any other commands.

vendor/bin/strata migration:install

Use --force or -f to run in production environments:

vendor/bin/strata migration:install --force

Running migration:run calls migration:install automatically, so explicit installation is optional.

migration:make

Generates a new migration file in the configured migrations directory. The filename is prefixed with a timestamp automatically.

vendor/bin/strata migration:make <filename>

To generate a create table migration with a pre-filled stub:

vendor/bin/strata migration:make create_users_table --create-table=users

To generate an alter table migration:

vendor/bin/strata migration:make add_email_to_users --alter-table=users

Omitting --create-table and --alter-table generates a blank migration. --create-table and --alter-table are mutually exclusive.

migration:run

Runs all pending migrations in chronological order. Migrations that have already run are skipped. All pending migrations are grouped into a single batch.

vendor/bin/strata migration:run

Use --force or -f to run in production:

vendor/bin/strata migration:run --force

migration:rollback

Rolls back all migrations in the last batch by calling their down() methods in reverse order.

vendor/bin/strata migration:rollback

Use --force or -f to run in production:

vendor/bin/strata migration:rollback --force

migration:status

Displays a table of all known migrations with their batch number and timestamp. Pending migrations appear with empty batch and timestamp columns.

vendor/bin/strata migration:status

 -------------------------------------------- ------- ---------------------
  Migration                                    Batch   Migrated At
 -------------------------------------------- ------- ---------------------
  2026_06_01_000000_create_users_table.php     1       2026-06-01 10:00:00
  2026_06_10_000000_create_posts_table.php     2       2026-06-10 14:30:00
  2026_06_15_000000_add_email_to_users.php
 -------------------------------------------- ------- ---------------------

Writing migrations

Migration files must return an anonymous class implementing MigrationInterface. The up() method applies the change; down() reverses it.

<?php

use Georgeff\Schema\Blueprint;
use Meritum\Migrations\SchemaInterface;
use Meritum\Migrations\MigrationInterface;

return new class implements MigrationInterface {

    public function up(SchemaInterface $schema): void
    {
        $schema->create('users', function (Blueprint $blueprint) {
            $blueprint->uuid()->unique()->primary();
            $blueprint->string('name');
            $blueprint->string('email')->unique();
            $blueprint->timestamps();
        });
    }

    public function down(SchemaInterface $schema): void
    {
        $schema->dropIfExists('users');
    }
};

SchemaInterface exposes create(), alter(), drop(), dropIfExists(), and tableExists(). The Blueprint API is provided by georgeff/schema.

Kernel integration

MigrationsModule and DatabaseModule register all services with the kernel. Use KernelBuilder as the entry point:

use Meritum\Migrations\Factory\KernelBuilder;

$kernel = KernelBuilder::build(environment: 'production');
$kernel->boot();
$kernel->run();

To extend the kernel with additional modules or service definitions, pass a ServiceRegistrar:

use Georgeff\Kernel\ServiceRegistrar;
use Meritum\Migrations\Factory\KernelBuilder;

$registrar = new ServiceRegistrar();
$registrar->register(new MyCustomModule());

$kernel = KernelBuilder::build(registrar: $registrar);
$kernel->boot();
$kernel->run();

KernelBuilder::build() accepts environment, registrar, and debug as named arguments.

License

MIT — see LICENSE.