phpdb-migration

Idempotent database migration engine for php-db/phpdb.

Features

• Idempotent migrations - Safe to run multiple times; operations check schema state before executing
• Definition mismatch detection - Compare existing schema against desired definitions with configurable strategies (ignore, report, alter)
• Rich helper methods - ensureTable(), ensureColumn(), ensureIndex(), ensureForeignKey(), ensureUniqueKey(), and more
• Dry-run preview - See what SQL would execute without making changes
• CLI commands - db:migrate and db:migrate:create via Symfony Console
• Laminas/Mezzio integration - ConfigProvider for container-based setup with laminas-cli

Installation

composer require peptolab/phpdb-migration

Quick Start

Standalone Usage

use PhpDb\Adapter\Adapter;
use PhpDb\Migration\MigrationRunner;
use PhpDb\Migration\MismatchStrategy;

$adapter = new Adapter([
    'driver'   => 'Pdo_Mysql',
    'database' => 'mydb',
    'username' => 'root',
    'password' => '',
]);

$runner = new MigrationRunner(
    adapter: $adapter,
    migrationsPath: __DIR__ . '/data/migrations',
    migrationsNamespace: 'MyApp\\Migrations',
    mismatchStrategy: MismatchStrategy::Report,
);

$runner->ensureMigrationsTable();
$results = $runner->runPending();

Laminas/Mezzio Integration

The package auto-registers via the ConfigProvider. Add your configuration:

// config/autoload/migrations.global.php
use PhpDb\Migration\MismatchStrategy;

return [
    'phpdb-migration' => [
        'migrations_path'      => getcwd() . '/data/migrations',
        'migrations_namespace' => 'Data\\Migration',
        'adapter_service'      => \PhpDb\Adapter\AdapterInterface::class,
        'resolution'           => MismatchStrategy::Report,
    ],
];

Configuration

Key	Type	Default	Description
migrations_path	string	getcwd() . '/data/migrations'	Directory containing migration files
migrations_namespace	string	App\Migration	PSR-4 namespace of migration classes
adapter_service	string	PhpDb\Adapter\AdapterInterface	Container service name for the adapter
resolution	MismatchStrategy|string	MismatchStrategy::Report	How to handle definition mismatches

Writing Migrations

Create a migration class that extends AbstractMigration:

<?php

declare(strict_types=1);

namespace Data\Migration;

use PhpDb\Migration\AbstractMigration;
use PhpDb\Sql\Ddl\Column;
use PhpDb\Sql\Ddl\Constraint;
use PhpDb\Sql\Ddl\CreateTable;

class Version20260101000000CreateUsersTable extends AbstractMigration
{
    public function getVersion(): string
    {
        return '20260101000000';
    }

    public function getDescription(): string
    {
        return 'Create users table';
    }

    protected function define(): void
    {
        $this->ensureTable('users', function (CreateTable $table) {
            $id = new Column\Integer('id');
            $id->setOption('unsigned', true);
            $id->setOption('auto_increment', true);
            $table->addColumn($id);

            $table->addColumn(new Column\Varchar('email', 255));
            $table->addColumn(new Column\Varchar('name', 100));

            $table->addConstraint(new Constraint\PrimaryKey(['id']));
        });

        $this->ensureIndex('users', 'idx_users_email', ['email'], true);
    }
}

Available Helper Methods

Schema Creation

• ensureTable(string $table, callable $callback) - Create table if not exists; validates definition if exists
• ensureColumn(string $table, ColumnInterface $column) - Add column if not exists; validates if exists
• ensureIndex(string $table, string $name, array $columns, bool $unique = false) - Add index if not exists
• ensureUniqueKey(string $table, string $name, array $columns) - Add unique constraint if not exists
• ensureForeignKey(string $table, string $name, string $col, string $refTable, string $refCol, string $onDelete, string $onUpdate) - Add FK if not exists

Schema Removal

• dropTableIfExists(string $table)
• dropColumnIfExists(string $table, string $column)
• dropIndexIfExists(string $table, string $index)
• dropForeignKeyIfExists(string $table, string $constraint)

Data & Raw SQL

• executeSql(string $sql, ?string $description) - Execute raw SQL
• executeSqlIf(bool $condition, string $sql, ?string $description, ?string $skipMessage) - Conditional SQL
• modifyColumn(string $table, string $column, string $definition, ?string $newName) - ALTER column
• insertRow(string $table, array $data) - Insert a row
• insertRowIfNotExists(string $table, array $data, array $uniqueColumns) - Conditional insert

Mismatch Strategy

When an ensure* method finds an existing schema object, the mismatch strategy determines what happens:

Strategy	Behavior
MismatchStrategy::Ignore	Skip silently (original behavior)
MismatchStrategy::Report	Log mismatch details in MigrationResult::$mismatches
MismatchStrategy::Alter	Auto-ALTER the schema to match the desired definition

Mismatches are tracked per migration and include: table name, column/constraint name, field that differs, expected value, and actual value.

CLI Commands

db:migrate

Run pending database migrations.

# Show migration status
vendor/bin/laminas db:migrate --status

# Preview SQL (dry run)
vendor/bin/laminas db:migrate --dry-run

# Run migrations
vendor/bin/laminas db:migrate --force

# Run with specific resolution strategy
vendor/bin/laminas db:migrate --force --resolution-strategy=alter

Options:

• --status, -s - Show migration status
• --dry-run - Preview SQL without executing
• --force, -f - Skip confirmation prompt
• --resolution-strategy, -r - Override mismatch strategy (ignore, report, alter)

db:migrate:create

Create a new migration file.

vendor/bin/laminas db:migrate:create "Add tags table"

This generates a timestamped migration file in the configured migrations directory.

Examples

See the docs/examples directory for complete migration examples.

License

BSD-3-Clause. See LICENSE.