Cloudflare 23：D1 ― Workers のそばに置く SQL データベース

D1 は、Cloudflare が運用する SQLite

D1 は、Cloudflare が運用するサーバーレスの SQL データベースです。中身は、世界でいちばん広く使われているデータベースエンジンの SQLite です。スマートフォンのアプリやブラウザの中でも動いている、小さくて頑丈なデータベースです。

「サーバーレス」とは、データベースのサーバーを自分で用意しなくてよい、という意味です。台数を決めることも、OS を更新することも、接続数を気にすることもありません。コマンド1つでデータベースができ、使った分だけ数えられます。

SQLite なので、ふつうの SQL がそのまま使えます。

Worker から D1 を呼ぶときは、接続文字列もパスワードも使いません。次のページで見る「バインディング」でつなぎます。

バインディング：コードからは env.DB で呼ぶ

Workers では、Cloudflare の他の機能を使うときにバインディングという仕組みを使います。設定ファイル（wrangler.jsonc または wrangler.toml）に「この名前で、このデータベースを使う」と書いておくと、Worker が動くときに、その名前のオブジェクトが env に入って渡されます。

図の右の設定では、binding に DB と書いています。すると、コードの中では env.DB として D1 を呼べます。名前は自由に付けられるので、データベースを2つ使うなら USERS_DB と LOGS_DB のように分けます。

この方式の良いところは、秘密の情報がコードにも設定にも出てこないことです。database_id はデータベースを指す番号にすぎず、それだけでは外から読み書きできません。「どの Worker がどのデータベースを使ってよいか」は、Cloudflare の側がアカウントの中で結び付けています。

TypeScript を使う場合は、wrangler types を実行すると、設定ファイルから env の型が作られます。env.DB を打ったときに、使えるメソッドが補完されるようになります。

本体は、1か所に住んでいる

D1 のデータベースは、作ったときに決まる1か所の拠点に本体が置かれます。場所は、ふつうは作った人の近く（または指定した地域）が選ばれます。

ここで大事なのは、Worker とデータベースの距離です。Worker は利用者のいちばん近くの拠点で動きます。東京の利用者なら東京で、ロンドンの利用者ならロンドンで動きます。ところが、データベースの本体は1か所なので、ロンドンの Worker から東京の D1 までは遠いのです。1回の問い合わせごとに、地球を半周して戻ってくることになります。

もう1つの性質は、1つのデータベースは、問い合わせを1つずつ順番に処理することです。SQLite の性質を受け継いでいます。1回の問い合わせが短ければ、1秒にたくさんさばけます。でも、索引の無い重い問い合わせが1つ混ざると、その間ほかの問い合わせは待たされます。

この2つから、D1 の設計の基本が見えてきます。

読み取りレプリカを、世界に置く

多くの Web アプリは、書き込みより読み取りのほうがずっと多いものです。記事は1回書かれて、何千回も読まれます。そこで D1 には、読み取りレプリカ（読み取り専用の写し）を世界の各地に置く機能があります。

仕組みはこうです。書き込み（INSERT・UPDATE・DELETE）は、必ず本体に届きます。本体は、変更の内容を各地のレプリカに順に送ります。読み取り（SELECT）は、Worker のいちばん近くにあるレプリカが答えます。ロンドンの利用者の読み取りは、ロンドンに近いレプリカで完結するので、速くなります。

ただし、変更がレプリカに届くまでにはわずかな遅れがあります。この送り方を「非同期」と呼びます。このため、何も工夫しないと、「書いた直後に読んだら、まだ古い内容が返ってきた」ということが起こりえます。

この問題を解くのが、次のページの Sessions API です。レプリカを使うときは、コードを Sessions API で書くことになっています。

読み取りレプリカは、データベースごとに管理画面や API で有効にします。2025年に公開ベータとして登場した機能なので、今の提供状況と追加料金の有無は公式で確かめてください。

Sessions API：自分が書いた内容を、確実に読む

Sessions API は、「一連の問い合わせ」をひとまとめ（セッション）にして、その中では時間が巻き戻らないことを保証する仕組みです。

鍵になるのがしおり（bookmark）です。しおりは「データベースのこの版まで見た」という印です。セッションの中で書き込むと、しおりが新しい版に進みます。次の読み取りは、しおりの版以降を持っているレプリカ（または本体）だけが答えます。だから、自分が書いた内容を読み落としません。

// 前の応答で渡したしおりを受け取る（無ければ最初はどこでもよい）
const bookmark = request.headers.get("x-d1-bookmark") ?? "first-unconstrained";
const session = env.DB.withSession(bookmark);

const post = await session
  .prepare("SELECT * FROM posts WHERE id = ?")
  .bind(id)
  .first();

const res = Response.json(post);
// 次のリクエストでも続きから読めるように、しおりを返す
res.headers.set("x-d1-bookmark", session.getBookmark() ?? "");
return res;

withSession には、しおりのほかに "first-primary"（最初は必ず本体に聞く）も渡せます。確実に最新を読みたい処理はこちらを使います。しおりを応答で返し、次のリクエストで受け取ると、ページをまたいでも巻き戻りません。

マイグレーション：表の形を、ファイルで管理する

アプリを育てていくと、表に列を足したり、索引を張ったりと、表の形（スキーマ）を変えることになります。これを本番のデータベースに手で打ち込むと、「手元と本番で形が違う」「誰がいつ変えたか分からない」という事故が起きます。

そこで D1 では、表の形の変更をマイグレーションという SQL ファイルに書いて残します。

npx wrangler d1 migrations create app add_tags
# migrations/0003_add_tags.sql ができるので、中に SQL を書く

npx wrangler d1 migrations apply app --local    # 手元で試す
npx wrangler d1 migrations apply app --remote   # 本番に当てる

ファイル名の先頭の番号の順に当てられます。どのファイルまで当てたかは、D1 の中の専用の表に記録されるので、同じファイルが2回当たることはありません。apply を実行すると、まだ当てていない分だけが走ります。

--local は、wrangler dev が手元で使う SQLite に当てます。本番の D1 に当てるには --remote を付けます。マイグレーションのファイルは Git に入れて、コードと一緒にレビューするのがおすすめです。

導入：作る → バインドする → 表を作る

D1 を使い始める手順は、次のとおりです。管理画面の「Storage & databases」から作ることもできますが、ここでは wrangler（34号）で進めます。

設定ファイルは、たとえば次のようになります。

# wrangler.toml の場合
[[d1_databases]]
binding = "DB"
database_name = "app"
database_id = "（d1 create で表示された ID）"

前提として、Workers のプロジェクトが1つ動いていることが必要です。D1 は Workers の無料プランでも使えるので、まずは無料で試せます。中身をのぞきたいときは、npx wrangler d1 execute app --remote --command "SELECT count(*) FROM posts" のように、コマンドから SQL を実行できます。

使い方：prepare して bind し、all で受け取る

D1 の基本の呼び方は、「SQL を用意（prepare）して、値を差し込み（bind）、実行する」の3段です。

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const author = new URL(request.url).searchParams.get("author") ?? "";

    const { results } = await env.DB
      .prepare("SELECT id, title FROM posts WHERE author = ? ORDER BY id DESC LIMIT 20")
      .bind(author)
      .all();

    return Response.json(results);
  },
};

? の場所に、bind で値が入ります。文字列をつなげて SQL を組み立てないでください。利用者の入力に SQL を混ぜ込まれる SQL インジェクションの原因になります。bind を使えば、値はあくまで値として扱われます。

実行のしかたは、欲しい結果に合わせて選びます。

batch に並べた文は、全部成功するか、全部取り消されるかのどちらかです。「注文を入れて、在庫を減らす」のように、片方だけ成功しては困る処理に使います。

料金と制限：読んだ行・書いた行・保存量で数える

D1 の料金は、読んだ行の数、書いた行の数、保存しているデータの量で数えます。データを Worker に返す通信量そのものには課金されません。

無料プランの1日の枠は、世界標準時（UTC）の0時、つまり日本時間の朝9時にリセットされます。枠を使い切ると、リセットまで問い合わせが失敗します。

注意したいのは、「読んだ行」は返した行の数ではなく、データベースが調べた行の数だという点です。10万行の表に索引が無いまま WHERE で1件を探すと、1件しか返さなくても10万行を読んだと数えられます。索引は、速さのためだけでなく、料金のためにも張ります。

1つのデータベースの大きさには上限があり、それ以上は大きくできません。大きくなりそうなら、利用者ごと・会社ごとにデータベースを分ける設計にします。

※2026年9月時点の情報です。料金・上限は変わるので、公式の Pricing と Limits のページで確かめてください。

よくある落とし穴

D1 でつまずきやすい点を並べます。どれも、手元の小さなデータでは気づかず、本番で初めて表に出ます。

重い集計（ランキング・月次の合計など）を、リクエストのたびに計算するのも避けます。Cron Triggers（25号）で定期的に計算して別の表に書いておき、画面ではそれを読むだけにすると、速く、安くなります。

D1 か、Postgres ＋ Hyperdrive か

Cloudflare から SQL のデータベースを使う道は、大きく2つあります。D1 と、よそにある Postgres や MySQL に Hyperdrive（26号）でつなぐ道です。

選び方の目安は、「データがもうどこかにあるか」です。すでに会社の Postgres があり、ほかのシステムもそれを使っているなら、データを動かさずに Hyperdrive でつなぐほうが自然です。これから新しく作る小さなアプリや、利用者ごとに独立したデータを持つアプリなら、D1 がいちばん手軽です。

途中で乗り換えることもできますが、SQL の方言（SQLite と Postgres の違い）の書き直しが要ります。最初に、データがどこまで大きくなりそうかを見積もっておきましょう。

他の号とのつながり

D1 は「行と列の表」の置き場です。Cloudflare にはほかにも置き場があり、得意なものが違います。組み合わせて使うのが普通です。

特に R2 との組み合わせは定番です。利用者がアップロードした画像そのものは R2 に置き、D1 には「誰の、どの画像が、どのキーで R2 にあるか」という表を持ちます。大きなファイルをデータベースに入れないことで、D1 の大きさの上限にも届きにくくなります。