D1は何を優先したのか:Workers Bindingで外部通信を持たないという価値選択

著者: ClaudeMix Team |

Cloudflare D1は、Workers Runtimeの外に出ないことを最優先している。

① D1は何を優先したか

一般的なフルスタック実装では、DBはWorkerとは別のホストで動くサーバーであり、アプリケーションは都度TCPやHTTPで外部へ接続する。Edge Runtime(Cloudflare Workers)でこれをやると、リクエストのたびに接続確立のコストがかかる。

D1はSQLite互換のデータベースで、Workers Runtimeへ直接Bindingされる。外部への接続を一切経由せず、env.DBとしてそのまま呼び出せる。

  • 【優先した価値】: Workers Runtimeの外に出ない、接続確立コストゼロの直結性
  • 【犠牲にした価値】: PostgreSQL/MySQL等が持つ拡張機能・全文検索・高度なトランザクション分離レベルといった、リレーショナルDBとしての機能の広さ

② ClaudeMixでやったこと

Before(概念): 一般的なフルスタック実装であれば、DBアクセスはORMを介して型安全なクエリを生成し、接続プール経由で外部DBへ接続する構成になる。以下は比較のための概念的なコードであり、ClaudeMix自身が過去にこの構成を採用していたわけではない。

// 一般的なORM経由の実装パターン(概念。ClaudeMix自身のコードではない)
const response = await prisma.impactQuizResponse.create({
  data: { id, quizId, selectedBucket, isCorrect },
});

After(実際のClaudeMix実装): impact-quizの回答記録と集計は、D1DatabaseへRaw SQLを直接.prepare().bind()して実行している。

// app/data-io/blog/impact-quiz/recordImpactQuizResponse.server.ts(抜粋)
await withRetry(
  () =>
    db
      .prepare(
        'INSERT INTO impact_quiz_responses (id, quiz_id, selected_bucket, is_correct) VALUES (?, ?, ?, ?)',
      )
      .bind(id, quizId, selectedBucket, isCorrect ? 1 : 0)
      .run(),
  retryConfig,
);

const aggregateResult = await withRetry(
  () =>
    db
      .prepare(
        'SELECT selected_bucket, COUNT(*) as count FROM impact_quiz_responses WHERE quiz_id = ? GROUP BY selected_bucket',
      )
      .bind(quizId)
      .all(),
  retryConfig,
);

Insightのテーブルビューアも同じ方針で、PRAGMA table_listをRaw SQLとしてそのまま実行している。

// app/data-io/insight/insightService.server.ts(抜粋)
const tablesResult = await withRetry(() => db.prepare('PRAGMA table_list').all(), retryConfig);

この2つの差分は「ORMという抽象レイヤーを挟むか、Raw SQLを直接書くか」という一点に絞られる。

③ 技術的負債

  • 【解消した負債】: ORMのバージョン依存やEdge Runtime対応可否を確認する手間がそもそも発生しない。SQL文と.bind()の引数順だけを見ればクエリの意味を追える。
  • 【新たに生まれた負債(あれば)】: migrations/schema.sqlはマイグレーション履歴を持たない。ファイル冒頭のコメントに「開発中はマイグレーション積み上げを行わない」「破壊的操作のため、本番運用フェーズへ移行する際は通常のマイグレーション方式へ切り替えること」と明記されている通り、現在impact_quiz_responsesテーブルがDROP→再作成方式の対象になっている。本番投入後にこの前提のままスキーマを変更すると、既存データを失う。

④ 経営翻訳

新設の相談窓口を、外部の代行業者を挟まず社内の担当者が直接お客様の台帳に手書きで記帳する運用にした。記帳ミスの余地は減るが、台帳のフォーマットを変えるときは今の台帳をいったん破棄して新しい台帳へ書き直す運用のままになっている。本番の台帳を扱うようになる前に、この破棄前提の運用を差分だけを積み上げる方式へ切り替える必要がある。