D1 マイグレーションワークフロー

Drizzle ORM を使用した Cloudflare D1 データベースマイグレーションのガイドワークフロー。

標準マイグレーションフロー

1. マイグレーションを生成

pnpm db:generate

drizzle/ (または設定したマイグレーションディレクトリ) に新しい .sql ファイルを作成します。

2. 生成された SQL を確認 (重要)

生成された SQL を適用する前に必ず確認してください。 Drizzle は単純なスキーマ変更に対して、破壊的なマイグレーションを生成することがあります。

注意フラグ: テーブル再作成

このパターンが見られた場合、マイグレーションは失敗する可能性が高いです:

CREATE TABLE `my_table_new` (...);
INSERT INTO `my_table_new` SELECT ..., `new_column`, ... FROM `my_table`;
--                                      ^^^ This column doesn't exist in old table!
DROP TABLE `my_table`;
ALTER TABLE `my_table_new` RENAME TO `my_table`;

原因: Drizzle スキーマでカラムの default 値を変更すると、テーブル全体の再作成がトリガーされます。INSERT SELECT は旧テーブルに存在しない新しいカラムを参照しています。

修正: 新しいカラムを追加するだけの場合 (既存カラムの型と制約に変更がない場合) は、以下に簡略化します:

ALTER TABLE `my_table` ADD COLUMN `new_column` TEXT DEFAULT 'value';

.sql ファイルを直接編集してから適用してください。

3. ローカルに適用

pnpm db:migrate:local
# または: npx wrangler d1 migrations apply DB_NAME --local

4. リモートに適用

pnpm db:migrate:remote
# または: npx wrangler d1 migrations apply DB_NAME --remote

テストする前に、必ずローカルとリモート両方に適用してください。 ローカルのみのマイグレーションは、「ローカルでは動くが本番環境で壊れる」という混乱を招きます。

5. 確認

# ローカルを確認
npx wrangler d1 execute DB_NAME --local --command "PRAGMA table_info(my_table)"

# リモートを確認
npx wrangler d1 execute DB_NAME --remote --command "PRAGMA table_info(my_table)"

停止したマイグレーションの修正

マイグレーションが部分的に適用された場合 (例: カラムは追加されたがマイグレーションが記録されなかった)、wrangler は再試行してダブりカラムエラーで失敗します。

症状: pnpm db:migrate が完了しているはずのマイグレーションでエラーが出ます。PRAGMA table_info ではカラムが存在しています。

診断

# 1. カラム/テーブルが存在することを確認
npx wrangler d1 execute DB_NAME --remote \
  --command "PRAGMA table_info(my_table)"

# 2. 記録されたマイグレーションを確認
npx wrangler d1 execute DB_NAME --remote \
  --command "SELECT * FROM d1_migrations ORDER BY id"

修正

# 3. 停止したマイグレーションを手動で記録
npx wrangler d1 execute DB_NAME --remote \
  --command "INSERT INTO d1_migrations (name, applied_at) VALUES ('0013_my_migration.sql', datetime('now'))"

# 4. 残りのマイグレーションを通常通り実行
pnpm db:migrate

予防策

• CREATE TABLE IF NOT EXISTS — 再実行しても安全
• ALTER TABLE ADD COLUMN — SQLite には IF NOT EXISTS バリアントがありません。カラムの存在を事前に確認するか、アプリケーションコードで try/catch を使用してください
• 生成された SQL を必ず確認 してから適用 (上記のステップ 2)

一括挿入のバッチ処理

D1 のパラメータ制限により、大量の複数行 INSERT で無音で失敗します。チャンクに分割します:

const BATCH_SIZE = 10;
for (let i = 0; i < allRows.length; i += BATCH_SIZE) {
  const batch = allRows.slice(i, i + BATCH_SIZE);
  await db.insert(myTable).values(batch);
}

理由: D1 は行数 × カラム数が約 100～150 パラメータを超えると失敗します。

カラム命名規則

コンテキスト	規則	例
Drizzle スキーマ	camelCase	caseNumber: text('case_number')
raw SQL クエリ	snake_case	UPDATE cases SET case_number = ?
API レスポンス	SQL エイリアスに合わせる	SELECT case_number FROM cases

新規プロジェクトセットアップ

新しいプロジェクト用に D1 データベースを作成する場合、この順序に従います:

1. Worker をデプロイ — npm run build && npx wrangler deploy
2. D1 データベースを作成 — npx wrangler d1 create project-name-db
3. database_id を wrangler.jsonc の d1_databases バインディングにコピー
4. 再デプロイ — npx wrangler deploy
5. マイグレーションを実行 — ローカルとリモート両方に適用