gevman/yiisoft-db-migration-dry-run

Dry-run SQL preview command for yiisoft/db-migration

1.0.0 2026-03-06 11:33 UTC

Requires

• php: ^8.1
• yiisoft/db: ^2.0
• yiisoft/db-migration: ^2.0
• yiisoft/db-mysql: ^2.0

Requires (Dev)

• phpunit/phpunit: ^10.5

MIT

• Gevorg Mansuryan

README

Adds --dry-run support to yiisoft/db-migration migrate:up.

What it does

• Extends migrate:up with:
  • --dry-run
  • --include-introspection
• Prints SQL preview without applying migrations.
• Keeps dry-run output concise by hiding migration list/progress noise.
• Filters migration history and schema-introspection queries by default.

Install

Yii project:

composer require gevman/yiisoft-db-migration-dry-run

Standalone, non-Yii project:

composer require yiisoft/db-migration yiisoft/db-mysql yiisoft/cache
composer require gevman/yiisoft-db-migration-dry-run

Yii3 integration

Map migrate:up to package command in your console command config:

<?php

declare(strict_types=1);

use Gevman\YiisoftDbMigrationDryRun\UpdateCommand as DryRunUpdateCommand;

return [
    'migrate:up' => DryRunUpdateCommand::class,
];

Then use the normal Yii console flow:

php yii migrate:up
php yii migrate:up --dry-run
php yii migrate:up --dry-run --include-introspection

Standalone yiisoft/db-migration

yiisoft/db-migration also works outside Yii. In that setup you usually keep migration config in yii-db-migration.php and use the stock binary:

vendor/bin/yii-db-migration migrate:new
vendor/bin/yii-db-migration migrate:up

Example yii-db-migration.php:

<?php

declare(strict_types=1);

return [
    'db' => new \Yiisoft\Db\Mysql\Connection(
        new \Yiisoft\Db\Mysql\Driver(
            'mysql:host=127.0.0.1;dbname=app;charset=utf8mb4',
            'root',
            'secret',
            [
                \PDO::ATTR_ERRMODE => \PDO::ERRMODE_EXCEPTION,
            ],
        ),
        new \Yiisoft\Db\Cache\SchemaCache(new \Yiisoft\Cache\ArrayCache()),
    ),
    'newMigrationNamespace' => '',
    'sourceNamespaces' => [],
    'newMigrationPath' => __DIR__ . '/migrations',
    'sourcePaths' => [
        __DIR__ . '/migrations',
    ],
    'historyTable' => '{{%migration}}',
    'migrationNameLimit' => 180,
    'useTablePrefix' => false,
    'container' => null,
    'maxSqlOutputLength' => null,
];

That is the same style used in non-Yii projects, where migrations are managed through a plain yii-db-migration.php file and a migrations/ directory.

Standalone dry-run integration

In a non-Yii project, vendor/bin/yii-db-migration still registers the original Yiisoft UpdateCommand, so --dry-run does not appear automatically.

To enable it, create a small custom console bootstrap and register Gevman\YiisoftDbMigrationDryRun\UpdateCommand instead of Yiisoft\Db\Migration\Command\UpdateCommand.

Example bin/db-migrate:

#!/usr/bin/env php
<?php

declare(strict_types=1);

use Gevman\YiisoftDbMigrationDryRun\UpdateCommand;
use Symfony\Component\Console\Application;
use Yiisoft\Db\Migration\Command\CreateCommand;
use Yiisoft\Db\Migration\Command\DownCommand;
use Yiisoft\Db\Migration\Command\HistoryCommand;
use Yiisoft\Db\Migration\Command\NewCommand;
use Yiisoft\Db\Migration\Command\RedoCommand;
use Yiisoft\Db\Migration\Informer\ConsoleMigrationInformer;
use Yiisoft\Db\Migration\Migrator;
use Yiisoft\Db\Migration\Runner\DownRunner;
use Yiisoft\Db\Migration\Runner\UpdateRunner;
use Yiisoft\Db\Migration\Service\Generate\CreateService;
use Yiisoft\Db\Migration\Service\MigrationService;
use Yiisoft\Injector\Injector;

require __DIR__ . '/../vendor/autoload.php';

$params = require __DIR__ . '/../yii-db-migration.php';
$db = $params['db'];

$migrator = new Migrator(
    $db,
    new ConsoleMigrationInformer(),
    $params['historyTable'],
    $params['migrationNameLimit'],
    $params['maxSqlOutputLength'],
);

$migrationService = new MigrationService($db, new Injector($params['container']), $migrator);
$migrationService->setNewMigrationNamespace($params['newMigrationNamespace']);
$migrationService->setNewMigrationPath($params['newMigrationPath']);
$migrationService->setSourceNamespaces($params['sourceNamespaces']);
$migrationService->setSourcePaths($params['sourcePaths']);

$createService = new CreateService($db, $params['useTablePrefix']);
$downRunner = new DownRunner($migrator);
$updateRunner = new UpdateRunner($migrator);

$application = new Application('Custom Project Migration Tool', '1.0.0');
$application->addCommands([
    new CreateCommand($createService, $migrationService, $migrator),
    new DownCommand($downRunner, $migrationService, $migrator),
    new HistoryCommand($migrationService, $migrator),
    new NewCommand($migrationService, $migrator),
    new RedoCommand($migrationService, $migrator, $downRunner, $updateRunner),
    new UpdateCommand($updateRunner, $migrationService, $migrator, $db),
]);
$application->run();

Then run:

php bin/db-migrate migrate:up --dry-run
php bin/db-migrate migrate:up --dry-run --include-introspection

Usage

Yii:

php yii migrate:up --dry-run

Standalone:

php bin/db-migrate migrate:up --dry-run
php bin/db-migrate migrate:up --dry-run --include-introspection

Options

Dry-run specific:

• --dry-run
  • Enables SQL preview mode for migrate:up.
  • Migrations are not applied; SQL is only collected and printed.
• --include-introspection
  • Includes schema-introspection queries in output.
  • By default, queries against information_schema and SHOW ... statements are filtered out.

Inherited from yiisoft/db-migration migrate:up:

Test

composer test

License

MIT. See LICENSE.