---
title: "移行"
description: "番号付けされた SQL マイグレーションは、Nibiru CLI によってドライブされます。"
---

マイグレーションは `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
```
## マイグレーションの実行
```bash
./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

常に部分的な失敗後でもエラーなく再実行できるマイグレーションを作成してください。
```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の場合:
```sql
CREATE TABLE IF NOT EXISTS api_registry (
    api_registry_id    SERIAL PRIMARY KEY,
    api_registry_name  TEXT NOT NULL UNIQUE
);
```
ALTER文では、サポートされているエンジンで`IF NOT EXISTS`句を使用することを推奨します。
```sql
ALTER TABLE "user" ADD COLUMN IF NOT EXISTS user_email VARCHAR(255);
```
エンジンが `IF NOT EXISTS` をサポートしていない場合は、変更がすでに存在する場合に何もしないガードクエリでステートメントをラップしてください。

## リセットコマンド

::: caution
リセットコマンドはマイグレーション監査テーブルをクリアしますが、データテーブルを削除しません。リセット後、次の `-mi` は *すべて* のマイグレーションを再実行します。リセットする前に、SQLが冪等であることを確認してください。
:::
```bash
./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` の場合、各マイグレーション後、モデルはライブスキーマから再生成されます。したがって、一般的なデプロイメントの手順は以下の通りです：
```bash
./nibiru -mi production
# Generator regenerates models on the next request.
./nibiru -cache-clear
```
ゼロダウンタイムデプロイメントのためには：ジェネレータをオフにします（`database = false`）し、依存するマイグレーションと共に再生成されたモデルをチェックインします。
