D1（サーバーレスSQLite）

解決する課題

• Workers アプリでリレーショナルなデータ（注文、ユーザー、在庫など）を扱いたいが、DB サーバーの構築・パッチ・スケーリングを自分で運用したくない
• SQL の使い慣れた表現力（JOIN、トランザクション、インデックス）を、エッジに近い場所で低レイテンシに使いたい
• 小〜中規模のワークロードで、常時起動のインスタンス課金ではなく使った分だけの課金にしたい
• KV や Durable Objects だけでは表現しにくい、複数テーブルにまたがる関係データを扱いたい

主要概念と用語

• データベース（Database）: D1 の管理単位。SQLite 互換のエンジンで動作する論理データベース
• バインディング（Binding）: Worker のコードから env 経由でデータベースへ直接アクセスするための接続定義。ネットワーク越しの資格情報管理が不要
• プリペアドステートメント（Prepared Statement）: パラメータ化された SQL 文を組み立てて実行する基本 API。SQL インジェクション対策にもなる
• バッチ（Batch）: 複数のステートメントをまとめて送信し、まとめて実行する仕組み
• 読み取りレプリカ（Read Replication）: 書き込みは単一のプライマリに集約されるが、読み取りは近傍のレプリカへ分散できる機能
• マイグレーション（Migrations）: スキーマ変更を管理・適用するための仕組み。ローカルとリモートの両方に適用できる
• Time Travel: 過去の任意時点の状態へデータベースを巻き戻せる、D1 固有の復元機能
• wrangler: D1 のデータベース作成・マイグレーション適用・クエリ実行などを行う Cloudflare の CLI ツール

仕様・制限・クォータ

• 1 つのデータベースあたりの最大サイズには上限があり、上限を超える見込みの大規模データセットには不向き（正確な値は公式ドキュメントを参照）
• 1 クエリで返却できる行数や、1 リクエストあたりの実行時間にも上限がある
• 書き込みは単一のプライマリに集約される設計のため、地理的に分散した大量同時書き込みには向かない
• 読み取りはレプリカを介して分散できるが、直近の書き込みが反映されるまでにわずかな遅延が生じ得る（結果整合性寄りの読み取りも選択可能）
• アカウントごとのデータベース数や、同時実行数などにもサービス上限がある

内部の仕組み

D1 は SQLite のファイルベースのデータベースエンジンをベースに、Cloudflare のネットワーク上でホストされたマネージドサービスとして提供されます。書き込みは単一のプライマリが受け持ち、更新内容は非同期に読み取りレプリカへ伝播します。Worker からのクエリはバインディングを通じて、書き込みならプライマリへ、読み取りなら設定に応じて近傍のレプリカへルーティングされます。

• クエリはプリペアドステートメントとして送信され、Workers ランタイムから直接呼び出される（別途コネクションプールを管理する必要がない）
• 複数ステートメントをまとめるバッチ実行により、往復回数を減らしてレイテンシを抑えられる
• バックアップや任意時点への復元は Time Travel によってサービス側の仕組みとして提供される

設計パターン / ベストプラクティス

• 参照が多く更新が少ないデータ（マスタデータ、設定、カタログなど）は D1 の読み取りレプリカの恩恵を受けやすい
• 高頻度カウンタや単純なキーバリューは、D1 よりも KV や Durable Objects の方が適する場合がある。関係データ・SQL クエリが必要なところに D1 を使う
• 複数の更新をまとめて行う場合は個別クエリの連投ではなくバッチでまとめ、往復回数を削減する
• スキーマ変更はマイグレーションとして管理し、ローカルでの検証後にリモートへ適用する運用にする
• インデックスを適切に張り、フルスキャンになりがちな WHERE 句や JOIN を避ける

運用・監視

• クエリの実行状況やエラーは Workers 側のログ・メトリクスと合わせて確認する
• スキーマ変更はマイグレーションファイルとして履歴管理し、環境ごと（ローカル / 本番）に適用状況をそろえる
• 誤った書き込みや障害からの復旧には Time Travel による任意時点への巻き戻しを利用できる
• クエリのレイテンシが悪化した場合は、インデックス設計・バッチ化・読み取りレプリカの利用状況を見直す

コスト

課金は基本的にリクエスト数（読み取り/書き込み）とストレージ使用量に応じた従量制です。具体的な単価や無料枠は変動するため、最新情報は公式ドキュメントを参照してください。

セキュリティ

• Worker からの接続はバインディング経由で行われ、資格情報をコードやネットワーク越しに扱う必要がない
• クエリはプリペアドステートメントでパラメータ化し、文字列連結による SQL インジェクションを避ける
• データベースへのアクセス権はアカウント・プロジェクト単位の権限管理に従う

関連サービス・比較

ハンズオン / CLI例

# D1 データベースを作成
wrangler d1 create my-app-db

# マイグレーション（スキーマ定義）をリモートに適用
wrangler d1 migrations apply my-app-db --remote

# ローカルでSQLを直接実行して動作確認
wrangler d1 execute my-app-db --local --command "SELECT * FROM users LIMIT 10"

# 本番データベースに対してSQLファイルを実行
wrangler d1 execute my-app-db --remote --file ./schema.sql