Migration

FrameworkとApplicationのPostgreSQL Migrationを明示Commandで確認・適用する。

ApplicationのDeployment工程からBlackOpsのPostgreSQL TableへMigrationを明示的に適用します。HTTP ServerやWorkerの起動時にはMigrationを実行しません。

Commandの登録境界

Public Console KernelはMigration Commandを常時登録し、対象Commandを実行したときだけconfig/database.phpの解決済みConnection ParameterとSchemaからRunnerを構成します。

// config/database.php（単一Connection互換形）
return [
    'connection' => [
        'driver' => 'pdo_pgsql',
        'host' => 'postgres',
        'port' => 5432,
        'dbname' => 'blackops',
        'user' => 'blackops',
        'password' => 'blackops',
    ],
    'schema' => 'blackops',
];

Schema名の既定値はblackopsです。変更する場合は、先頭を小文字英字またはunderscoreとし、以降を小文字英数字またはunderscoreとする安全なPostgreSQL Identifierを指定します。

Deployment手順

Deployment前にStatusとDry-runを確認し、その後にNon-interactiveで適用します。

php blackops database:status --no-interaction
php blackops database:migrate --dry-run --no-interaction
php blackops database:migrate --no-interaction
php blackops database:status --no-interaction

statusはApplied／Pending件数とVersionを表示し、Databaseを変更しません。--dry-runはBaselineとMetadata更新のSQL Planを表示しますが、Schema、Metadata Table、Framework Data Tableを作成・変更しません。

Pendingがない状態でmigrateを再実行すると、No pending migrations.と表示して成功します。

Application Migrations

Project Rootにmigrations/がある場合、Database CommandはFramework Migrationに加えてApp\MigrationsのVersion*.phpを読み込みます。DirectoryがないApplicationはFramework Migrationだけを扱うため、空Directoryを作る必要はありません。

Application MigrationはFramework Migrationと同じConnection、Framework Schema内のschema_migrations Metadata Table、transactional／all-or-nothing設定を共有します。RunnerはFramework Migrationを先に実行し、その後にApplication MigrationをVersion Class順で実行します。

Application MigrationはDoctrine標準Constructorを使います。FrameworkはSchema名を自動注入しないため、ApplicationがTableのSchemaとSQLを明示します。Install直後のSkeletonにはOrder Journey用のApplication Migrationがあり、database:migrate後にquickstart_ordersとquickstart_order_commitsを作ります。HTTP起動だけではこれらのTableを作りません。

<?php

declare(strict_types=1);

namespace App\Migrations;

use Doctrine\DBAL\Schema\Schema;
use Doctrine\Migrations\AbstractMigration;

final class Version20260718000000 extends AbstractMigration
{
    public function getDescription(): string
    {
        return 'CreateQuickstartOrderTables';
    }

    public function up(Schema $schema): void
    {
        $this->addSql(
            'CREATE TABLE public.quickstart_orders (reference VARCHAR(64) NOT NULL, PRIMARY KEY (reference))',
        );
        $this->addSql(
            'CREATE TABLE public.quickstart_order_commits (reference VARCHAR(64) NOT NULL, PRIMARY KEY (reference))',
        );
    }

    public function down(Schema $schema): void
    {
        $this->addSql('DROP TABLE public.quickstart_order_commits');
        $this->addSql('DROP TABLE public.quickstart_orders');
    }
}

Database Commandは実行時にVersion*.phpを直接読み込みます。Parse Error、App\Migrations以外のNamespace、File名と異なるClass、AbstractMigrationでないClassを検出すると失敗します。migrationsがFileまたはsymlinkの場合も無視せず拒否します。

HTTP、Worker、Scheduler、Build、Consoleのlist／helpはMigration Directoryを読み込まず、MigrationやDDLを暗黙実行しません。

初期Dataも投入するDeploymentでは、Migration後にApplicationをBuildしてからRoot Seederを実行します。Seederの作り方と責任境界はSeederを参照してください。

php blackops database:migrate
php blackops build:compile
php blackops database:seed

BlackOpsはRollback Commandを提供しません。down()はDoctrine Migrations互換の定義ですが、Framework CLIから実行する経路はありません。Migrationを取り消す場合は、逆操作を新しいForward Migrationとして適用してください。設定の実例はDatabaseを参照します。