Serverless SQL with D1

After this lesson you'll be able to create a D1 database, apply a schema with migrations, query it from a Worker with prepared statements, and explain when D1 is the right choice over KV.

D1 is Cloudflare's managed relational database: real SQL, built on SQLite, callable from a Worker with no connection pool, no server to provision, and no idle cost. If KV is a distributed key-value cache, D1 is the thing you reach for the moment your data has relationships — a user has many orders, an order has many line items, and you need to query and join across them with actual transactional guarantees. Under the hood, a D1 database is a SQLite file that Cloudflare manages, replicates, and serves through a HTTP/Worker-binding API rather than a raw file handle.

How it works

A few architectural pieces matter for how you design around D1:

• One primary, many read replicas. Each D1 database has a single primary location where writes land, and D1 can maintain read replicas in other regions to serve read queries with lower latency and higher aggregate read throughput. Writes are still serialized through the primary — D1 does not give you multi-writer replication.
• Sessions for read consistency. Because reads can be served from a replica that lags slightly behind the primary, D1 exposes a Sessions API (withSession()) so a sequence of queries in one request can pin to a consistent view — useful right after a write, when you need to read your own write back.
• Time Travel for recovery. D1 automatically checkpoints your database so you can restore it to any minute within the last 30 days — point-in-time recovery with no separate backup job to run.
• Access is query-based, not a raw connection. You never open a socket to D1. A Worker gets a binding (env.DB) and calls .prepare(sql).bind(params) to build a parameterized statement, then .run(), .first(), or .raw() to execute it and shape the result.

Worked example

Create the database with Wrangler:

npx wrangler d1 create app-db

This prints a database_id. Add the binding to wrangler.toml:

[[d1_databases]]
binding = "DB"
database_name = "app-db"
database_id = "<the-id-wrangler-printed>"

Define the schema as a migration file rather than hand-running SQL against production:

npx wrangler d1 migrations create app-db create_users_and_posts

This scaffolds a numbered file under migrations/. Fill it in:

-- migrations/0001_create_users_and_posts.sql
CREATE TABLE users (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  email TEXT NOT NULL UNIQUE,
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE TABLE posts (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  user_id INTEGER NOT NULL REFERENCES users(id),
  title TEXT NOT NULL,
  created_at TEXT NOT NULL DEFAULT (datetime('now'))
);

CREATE INDEX idx_posts_user_id ON posts(user_id);

Apply it locally, then to production, once you're satisfied:

npx wrangler d1 migrations apply app-db --local
npx wrangler d1 migrations apply app-db --remote

Query it from a Worker using prepared statements — never string-concatenate user input into SQL:

export interface Env {
  DB: D1Database;
}

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

    // Prepared statement with a bound parameter — safe against SQL injection.
    const { results } = await env.DB.prepare(
      `SELECT posts.id, posts.title, posts.created_at
       FROM posts
       JOIN users ON users.id = posts.user_id
       WHERE users.id = ?
       ORDER BY posts.created_at DESC`
    )
      .bind(userId)
      .run();

    return Response.json(results);
  },
} satisfies ExportedHandler<Env>;

Writes work the same way — .run() on an INSERT/UPDATE gives you a meta object with changes and last_row_id. For multiple statements that must succeed or fail together, use env.DB.batch([...]), which runs them sequentially as a single transaction.

Pricing

D1 bills on rows read, rows written, and storage — not on compute time or open connections:

There's no charge for data transfer out of D1, and no charge for having many databases sitting idle — D1 only bills for rows actually touched and bytes actually stored. Per Cloudflare's current limits, a single database maxes out at 10 GB on the Paid plan (500 MB on Free), and an account can hold up to 50,000 databases on Paid (10 on Free) — a useful pattern for per-tenant isolation. Confirm current figures on the pricing page linked below before quoting them, since pricing is subject to change.

Use cases

• Relational application data — users, orders, posts, comments: anything where rows reference other rows and you'll eventually need a JOIN to answer a real question.
• Anything needing transactions — "debit this account and credit that one, both or neither" is a job for SQL transactions (batch()), not a pattern you can safely build on KV's independent key writes.
• Per-tenant databases — because creating a D1 database is free and cheap at scale, a common pattern is one database per customer/tenant for strong data isolation, rather than one shared database with a tenant_id column.
• Read-heavy content with occasional writes — blog posts, product catalogs, comment threads — where read replicas cut latency for the common case (reading) while writes stay infrequent enough that primary-only writes aren't a bottleneck.