# AI エージェントに本番 DB の migration を任せる（破壊的 SQL を構造的に実行できないランナー） ## 誰向け AI コーディングエージェント（Claude Code / Codex 等）に開発を任せているが、 **本番 DB への DDL だけは毎回人間が SQL エディタに貼っている**チーム向け。 その1操作を安全に AI 側へ移すための設計と、実際に踏んだ落とし穴をまとめる。 ## 前提と結論 - エージェントの安全機構（コマンド分類器）は「本番デプロイ」「本番 DB 書き込み」を既定で止める。 **これは正しい**ので解除しようとしない。解除ではなく、**許可する操作の範囲を狭める**。 - 具体策: 「**破壊的な SQL を構造的に実行できないランナー**」を1本だけ作り、 **そのスクリプトのパスだけ**を許可リストに入れる。`node scripts/*` のような広い許可は作らない。 - エージェント自身に許可を追加させない（自己権限付与は分類器が止めるし、止めるべき）。 人が1回だけ許可を入れる。以後の migration 適用はエージェントが完結する。 ## ランナーの設計（ここが本体） ### 1. allowlist 文法（正規表現スキャンにしない） 禁止語を grep する実装は、文字列リテラルやコメント中の `drop` を誤検知し、 逆に `ALTER ... DROP COLUMN` のような複合構文を取りこぼす。 **SQL を字句分割 → 文単位にパース → 許可した構文だけを再構築して実行**する。 - 許可: `create table if not exists` / `alter table ... add column` / `create index` / `comment on` / `create policy` / `enable row level security` - 拒否: `drop` / `truncate` / `delete` / `update` / `alter ... drop column` / `alter ... type` / `grant` / `revoke` / ロール操作 - **1文でも禁止構文があればバッチ全体を拒否**（部分適用を作らない） ### 2. 実行の約束 - 単一トランザクション。失敗時は rollback - 適用前後で対象テーブルの `information_schema.columns` を取り、**差分を出力** - 対象テーブルの `count(*)` が変化したら rollback（DDL なら行数は不変） - 実行記録を JSONL に追記。**同じ SQL のハッシュが成功済みなら no-op**（二重適用防止） - `--list` / `--dry-run` は読み取り専用。`--apply` のときだけ書き込む ### 3. 成功条件を厳しくする（これが最重要） `exit 0` と「適用成功」を**実際の効果が確認できたときだけ**出す。 - `add column` を含むのに適用後もカラムが存在しない → **exit 1 で失敗** - 元から存在していた（冪等 no-op）場合は「**既に適用済み**」と明確に区別して出す これが無いと「成功と報告されたが何も起きていない」沈黙 failure を人が検出できない。 実際に、この検証を足すまで区別がつかず、調査が半日分往復した。 ## 踏んだ落とし穴（そのまま再現する） ### TLS: `SELF_SIGNED_CERT_IN_CHAIN` マネージド DB の多くは**ベンダー独自のプライベート CA** を使う（公開 CA ではない）。 検証を切る（`rejectUnauthorized:false`）のは本番 DDL ツールでは不可。 正しくは CA を明示する: ``` openssl s_client -starttls postgres -connect :5432 -showcerts ' > root.pem NODE_EXTRA_CA_CERTS=root.pem node scripts/apply-migration.mjs --list ``` ベンダーの公式配布 URL があればそちらを使う（古い記事の URL は 404 になっていることがある）。 ### event trigger ガードの過剰反応 「有効な event trigger がある DB では適用しない」は妥当な防御だが、 **マネージド DB は標準で複数の event trigger を持つ**（スキーマキャッシュのリロード、 拡張機能のアクセス制御など）。名前の allowlist にして、**未知の名前だけを拒否**し、 拒否時はその名前を表示する。名前を出さないと原因に辿り着けない。 ### 「未適用」の判定根拠を確かめる `--list` の「未適用」が**履歴テーブル基準**なのか**オブジェクト実在基準**なのかで意味が全く違う。 新規に置いたプローブ用ファイルは履歴に無いので必ず「未適用」と出る。 **判定根拠を確認せずに「本番にカランが無い」と断定しない**（筆者はこれで誤報を出した）。 ## 許可の入れ方（人の操作は生涯1回） 1. ランナーを作り、**人に渡す前に自分でテストを走らせる**（禁止構文を含む SQL を食わせて拒否されること） 2. 許可は**そのスクリプトのフルパス1本だけ** 3. 設定ファイルを人に手で編集させない。**ワンクリックで実行できる形**（デスクトップのランチャー等）で渡し、 スクリプト側が「これから許可する操作」を画面に出してから書き込む 4. ランチャーは**終了コードを必ず伝播**させる。しないと失敗が `OK` と表示され、双方が誤診する ## 検証チェックリスト（完了判定） - [ ] 禁止構文入り SQL が exit 2 で**バッチごと**拒否される - [ ] テストが全件 pass（Windows 等、実際に動かす OS で実行する。コンテナ内の緑は別環境の保証にならない） - [ ] `--dry-run` が実行計画（追加されるカラム名）を出す - [ ] `--apply` 後に「適用成功」または「既に適用済み」が**実在確認付き**で出る - [ ] 同じ migration の2回目が no-op になる ## 向いていないケース - データ移行を伴う migration（`update` が必要なもの）はこのランナーの対象外。設計上通さない - 複数環境へ一括適用したい場合は、環境ごとに別の許可と確認を用意する（1本の許可で全環境を触らせない） ---