ローカルD1環境の自律化:手順書ではなく破壊による初期化スクリプトを選んだ判断
著者: ClaudeMix Team |
ローカルD1環境のセットアップを、開発者が都度コマンドを打つ運用にするのではなく、1つのスクリプトが.wranglerを物理削除してスキーマから再生成する設計にした。
① やったこと
案1(不採用): 開発者がローカル環境のセットアップに困るたびに、npx wrangler d1 executeコマンドをその都度手で組み立てて実行する運用を検討した。手順書に頼る運用であり、実装としては存在しない。
案2(採用): scripts/env/db-reset/engine.tsが、.wranglerディレクトリの削除・migrations/schema.sqlの適用・migrations/seed.sqlの適用を1つのコマンド(npm run db-reset)にまとめている。
// scripts/env/db-reset/engine.ts(抜粋)
function cleanWrangler(options: Options): void {
if (options.remote) return;
try {
fs.rmSync(path.join(ROOT, '.wrangler'), { recursive: true, force: true });
} catch (e: unknown) {
log(' ⚠️ Some files are busy (dev server running?), continuing...');
}
}
async function perform(options: Options): Promise<void> {
if (options.mode === 'init' || options.mode === 'reset') {
cleanWrangler(options);
executeSql('migrations/schema.sql', options);
}
if (options.mode === 'seed' || options.mode === 'reset') {
executeSql('migrations/seed.sql', options);
}
}差分は、セットアップ手順を人間の手順書に置くか、1コマンドのスクリプトに置くかという一点にある。
② 設計判断
- 【優先した価値】: 誰が実行しても
migrations/*.sqlという同じ入力から同じ結果が再現される決定性。手順書の読み違いによる環境差分が構造的に発生しない。 - 【犠牲にした価値】: 即時性。
--localかつinit/resetモードのときは常に.wranglerを削除してから再構築するため、既存のローカルデータを部分的にだけ残すような軽量な運用はできない。
③ 技術的負債
- 【採用した案が抱える負債】:
cleanWranglerは.wrangler削除が失敗した場合、例外をcatchして警告ログを出すだけで処理を継続する。npm run dev等でdevサーバーが起動しファイルをロックしたままこのスクリプトを実行すると、「busy」警告が出た上で、削除しきれなかった.wranglerの残骸を抱えたままmigrations/schema.sqlの適用に進む。限界が来る条件は「devサーバー等が.wranglerのファイルを掴んだ状態でdb-resetを実行したとき」で、その場合の状態整合性はスクリプトの責任範囲外に置かれている。
④ 経営翻訳
新拠点の什器を毎回同じ配置で組み立てるため、担当者が現地判断で組むのではなく、単一の組立指示書だけを渡す運用にした。指示書は「まず古い什器をすべて撤去してから、決まった順番で新しい什器を運び込む」という手順になっている。ただし撤去作業中に別の作業員がまだその場で作業していた場合、撤去担当は「作業中のため一部撤去できませんでした」と記録するだけで、そのまま次の搬入作業に進んでしまう。