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 <db-host>:5432 -showcerts </dev/null \
  | awk '/BEGIN CERT/{n++} n==<ルートの番号>' > 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本の許可で全環境を触らせない）