ローカル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を実行したとき」で、その場合の状態整合性はスクリプトの責任範囲外に置かれている。

④ 経営翻訳

新拠点の什器を毎回同じ配置で組み立てるため、担当者が現地判断で組むのではなく、単一の組立指示書だけを渡す運用にした。指示書は「まず古い什器をすべて撤去してから、決まった順番で新しい什器を運び込む」という手順になっている。ただし撤去作業中に別の作業員がまだその場で作業していた場合、撤去担当は「作業中のため一部撤去できませんでした」と記録するだけで、そのまま次の搬入作業に進んでしまう。