移行

マイグレーションは application/settings/config/database/ に配置され、数字順で実行されます。CLI はどのファイルが実行されたかを追跡し、後続の呼び出しではそれらをスキップします。

ファイル名付け

NNN-<slug>.sql

• NNN: ソート順序のゼロパディングされた3桁の数字。
• <slug>: ハイフン区切りの説明 (add-account-email, create-acl-data)。

例の進行:

001-acl.sql
002-account.sql
003-api_registry.sql
004-timeanddate.sql
005-user.sql
006-user_to_account.sql
007-timeanddate_to_account.sql
008-user_to_acl.sql
009-account_to_api_registry.sql
010-timeanddate_to_user.sql
011-acl-data.sql
012-add-unique-key-user.sql
013-add-account-email.sql

マイグレーションの実行

./nibiru -mi local                              # APPLICATION_ENV=development
APPLICATION_ENV=staging   ./nibiru -mi staging
APPLICATION_ENV=production ./nibiru -mi production

{env} 引数と APPLICATION_ENV は一致する必要があります。マイグレーションは、settings.<env>.ini の [DATABASE] セクションで設定されたデータベースを対象としています。

ランナーが何をするか

各 *.sql ファイルを数値順に:

1. _migrations テーブルでファイル名を検索します。
2. 存在しない場合、ドライバーが DDL トランザクションをサポートする場合はトランザクションを開き、ファイルを実行し、成功するとレコードを挿入します。
3. ステートメントに失敗した場合は、ロールバックして非ゼロで終了します。

_migrations テーブルは初回実行時に自動的に作成されます。

Idempotent SQL

常に部分的な失敗後でもエラーなく再実行できるマイグレーションを作成してください。

CREATE TABLE IF NOT EXISTS api_registry (
    api_registry_id    INT(11) NOT NULL AUTO_INCREMENT,
    api_registry_name  VARCHAR(255) NOT NULL,
    PRIMARY KEY (api_registry_id),
    UNIQUE KEY api_registry_name_uk (api_registry_name)
) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4;

PostgreSQLの場合:

CREATE TABLE IF NOT EXISTS api_registry (
    api_registry_id    SERIAL PRIMARY KEY,
    api_registry_name  TEXT NOT NULL UNIQUE
);

ALTER文では、サポートされているエンジンでIF NOT EXISTS句を使用することを推奨します。

ALTER TABLE "user" ADD COLUMN IF NOT EXISTS user_email VARCHAR(255);

エンジンが IF NOT EXISTS をサポートしていない場合は、変更がすでに存在する場合に何もしないガードクエリでステートメントをラップしてください。

リセットコマンド

::: caution リセットコマンドはマイグレーション監査テーブルをクリアしますが、データテーブルを削除しません。リセット後、次の -mi は すべて のマイグレーションを再実行します。リセットする前に、SQLが冪等であることを確認してください。 :::

./nibiru -mi-reset local                       # forget all applied migrations
./nibiru -mi-reset-file 005-user.sql local     # forget a single file

単一ファイルのフォームは、以前に適用されたマイグレーションでバグを修正した後、そのファイルのみ再実行したい場合に役立ちます。

ブランチの清掃

並行して2人のエンジニアが作業している場合、両方が 015-… を追加すると衝突する可能性があります。助ける慣習：

• プルリクエストタイトルで番号を予約する SQL を書く前に。
• ホットフィックスには大きな隙間を使用する（例：099、199、299 を緊急の cherry-picks に予約する）。
• 破壊的マイグレーションよりも追加的なマイグレーションを優先する（新しいテーブル、新しい列）。それらはよりきれいにマージします。

マージの整理

長期間にわたるプロジェクトでは、定期的に古いマイグレーションを1つのシードファイルにまとめ、現在のスキーマを表します。元のファイルはarchive/に移動させ、監査トレールが存在するようにし、新しい000-baseline-2026.sqlを作成して一度にすべてを作ります。マイグレーションランナーを更新し、古いファイルが適用されたことをマークするために手動でINSERT INTO _migrationsを行います。

スキーマファーストモデル

[GENERATOR] database = true の場合、各マイグレーション後、モデルはライブスキーマから再生成されます。したがって、一般的なデプロイメントの手順は以下の通りです：

./nibiru -mi production
# Generator regenerates models on the next request.
./nibiru -cache-clear

ゼロダウンタイムデプロイメントのためには：ジェネレータをオフにします（database = false）し、依存するマイグレーションと共に再生成されたモデルをチェックインします。