Cloudflare D1 — Serverless SQL Database on the Edge

Posted on: 4/26/2026 2:14:44 PM

When your web application needs a database but you don't want to manage servers, worry about scaling, or pay when there's no traffic — Cloudflare D1 is the answer. It's a serverless SQL database built on SQLite, running directly on Cloudflare's global edge network. No provisioning, no connection pooling, no significant cold starts — just write SQL and deploy. This article provides a deep analysis of D1's internal architecture, Workers integration, global read replication strategy, and when you should (or shouldn't) choose D1 for your project.

1. Why Cloudflare D1?

Before D1, if you built applications on Cloudflare Workers (serverless edge functions), you had two options for structured data storage:

D1 fills the gap between KV (too simple) and external databases (too far away). It brings full SQL to the edge with low latency and near-zero cost when idle.

graph LR
    subgraph "Before D1"
        W1["Workers"] -->|"High latency"| EDB["External DB
us-east-1"]
        W1 -->|"Key-value only"| KV["Workers KV"]
    end
    subgraph "With D1"
        W2["Workers"] -->|"~0ms binding"| D1["D1 Database
SQLite on Edge"]
        D1 -->|"Auto replicate"| R1["Read Replica
Asia"]
        D1 -->|"Auto replicate"| R2["Read Replica
Europe"]
    end
    style D1 fill:#e94560,stroke:#fff,color:#fff
    style W2 fill:#f8f9fa,stroke:#e94560,color:#2c3e50
    style EDB fill:#f8f9fa,stroke:#e0e0e0,color:#888
    style R1 fill:#4CAF50,stroke:#fff,color:#fff
    style R2 fill:#4CAF50,stroke:#fff,color:#fff

2. D1 Internal Architecture

D1 is built on two core Cloudflare primitives:

2.1. SQLite as the SQL Engine

Instead of building a database engine from scratch, Cloudflare chose SQLite — the most widely deployed database in the world with over 1 trillion active databases. SQLite provides:

• Full SQL: JOIN, subqueries, window functions, CTEs, JSON functions, full-text search (FTS5)
• Zero configuration: No buffer pool tuning, shared memory, or connection limit management
• Single-file storage: The entire database is one file — easy to backup, replicate, and migrate
• Battle-tested: Over 20 years of development, used in every smartphone, browser, and operating system

2.2. Durable Objects as the Coordination Layer

Each D1 database is hosted by a Durable Object — ensuring that at any point in time, there is exactly one instance of the database running globally. This solves the consistency problem without requiring complex distributed consensus protocols:

graph TB
    subgraph "Global Cloudflare Network"
        subgraph "Primary Region"
            DO["Durable Object
(Single Writer)"]
            DB["SQLite File
(WAL Mode)"]
            DO --> DB
        end
        subgraph "Edge PoPs"
            E1["PoP Singapore"]
            E2["PoP Frankfurt"]
            E3["PoP São Paulo"]
        end
    end
    E1 -->|"Read/Write requests"| DO
    E2 -->|"Read/Write requests"| DO
    E3 -->|"Read/Write requests"| DO
    style DO fill:#e94560,stroke:#fff,color:#fff
    style DB fill:#2c3e50,stroke:#fff,color:#fff
    style E1 fill:#f8f9fa,stroke:#e94560,color:#2c3e50
    style E2 fill:#f8f9fa,stroke:#e94560,color:#2c3e50
    style E3 fill:#f8f9fa,stroke:#e94560,color:#2c3e50

3. Workers Integration

D1 is designed for zero-config integration with Workers through bindings — no connection strings, no drivers, no connection pooling needed:

# wrangler.toml — declare D1 binding
name = "my-app"
main = "src/index.ts"
compatibility_date = "2026-04-01"

[[d1_databases]]
binding = "DB"
database_name = "my-production-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

// src/index.ts — Worker using D1
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const url = new URL(request.url);

    if (url.pathname === "/api/products") {
      // Prepared statement — auto-parameterized, prevents SQL injection
      const { results } = await env.DB.prepare(
        "SELECT id, name, price FROM products WHERE category = ? ORDER BY created_at DESC LIMIT ?"
      )
        .bind("electronics", 20)
        .all();

      return Response.json(results);
    }

    if (url.pathname === "/api/products" && request.method === "POST") {
      const body = await request.json();

      // Batch operations — multiple statements in 1 round-trip
      const statements = [
        env.DB.prepare(
          "INSERT INTO products (name, price, category) VALUES (?, ?, ?)"
        ).bind(body.name, body.price, body.category),
        env.DB.prepare(
          "INSERT INTO audit_log (action, entity, timestamp) VALUES (?, ?, ?)"
        ).bind("CREATE", "product", new Date().toISOString()),
      ];

      const results = await env.DB.batch(statements);
      return Response.json({ success: true, results });
    }

    return new Response("Not found", { status: 404 });
  },
};

interface Env {
  DB: D1Database;
}

3.1. Client API Reference

4. Global Read Replication — Sessions API

The biggest limitation of the single-writer architecture: if the primary database is in the US, users in Vietnam face ~200ms latency for every query. The Sessions API solves this by automatically creating read replicas close to users:

sequenceDiagram
    participant User as User (Vietnam)
    participant Edge as Edge PoP (Singapore)
    participant Replica as Read Replica (Singapore)
    participant Primary as Primary DB (US)

    User->>Edge: SELECT query
    Edge->>Replica: Read from local replica
    Replica-->>Edge: Result (< 5ms)
    Edge-->>User: Fast response

    User->>Edge: INSERT/UPDATE query
    Edge->>Primary: Route to primary
    Primary-->>Edge: Write confirmed + commit token
    Edge-->>User: Response + new commit token

    Note over Edge,Replica: Replica receives async replication
    Note over User,Edge: Next read uses commit token
to ensure sequential consistency

4.1. Commit Tokens — Ensuring Sequential Consistency

The classic problem with async replication: read-after-write inconsistency. A user inserts a row, but the next read goes to a replica that hasn't synced yet — the newly written data is invisible. D1 solves this with commit tokens (Lamport timestamps):

// Using Sessions API with commit tokens
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    // Get commit token from cookie or header
    const token = request.headers.get("x-d1-token") || "";

    // Create session with token — D1 ensures replica has synced to at least this token
    const session = env.DB.withSession(token);

    if (request.method === "POST") {
      // Writes always go to primary
      const result = await session
        .prepare("INSERT INTO posts (title, body) VALUES (?, ?)")
        .bind("Hello", "World")
        .run();

      // Return new commit token — client sends it back with next request
      return Response.json(
        { success: true },
        { headers: { "x-d1-token": result.meta.token } }
      );
    }

    // Reads can go to nearest replica (if synced to token)
    const { results } = await session
      .prepare("SELECT * FROM posts ORDER BY id DESC LIMIT 10")
      .all();

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

5. Time Travel — Point-in-Time Recovery

D1 automatically backs up every minute (no configuration needed) and allows restoring the database to any point within the last 30 days:

# List bookmarks (named restore points)
npx wrangler d1 time-travel info my-production-db

# Restore to a specific point in time
npx wrangler d1 time-travel restore my-production-db \
  --timestamp "2026-04-25T10:30:00Z"

# Or restore to a bookmark
npx wrangler d1 time-travel restore my-production-db \
  --bookmark "before-migration-v42"

# Create bookmark before running a risky migration
npx wrangler d1 time-travel bookmark my-production-db \
  --name "before-migration-v42"

6. Schema Migration and Computed Columns

6.1. Migrations with Wrangler

# Create migration file
npx wrangler d1 migrations create my-db add-user-profiles

# File created at migrations/0001_add-user-profiles.sql

-- migrations/0001_add-user-profiles.sql
CREATE TABLE IF NOT EXISTS user_profiles (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id TEXT NOT NULL UNIQUE,
    display_name TEXT NOT NULL,
    bio TEXT,
    avatar_url TEXT,
    metadata JSON,
    created_at TEXT DEFAULT (datetime('now')),
    updated_at TEXT DEFAULT (datetime('now'))
);

CREATE INDEX idx_user_profiles_user_id ON user_profiles(user_id);

-- Computed column — auto-extracted from JSON
ALTER TABLE user_profiles
ADD COLUMN location TEXT
GENERATED ALWAYS AS (json_extract(metadata, '$.location')) STORED;

# Apply migration to production (or preview first)
npx wrangler d1 migrations apply my-db --remote

# Check migration status
npx wrangler d1 migrations list my-db --remote

6.2. Computed Columns — database-level calculations

Computed columns allow D1 to automatically calculate values from other columns or JSON data. Particularly useful when storing flexible JSON but still needing fast indexed queries:

-- Store settings as JSON, but extract frequently queried fields
CREATE TABLE products (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    data JSON NOT NULL,
    -- Computed columns — auto-extracted from JSON
    price REAL GENERATED ALWAYS AS (json_extract(data, '$.price')) STORED,
    category TEXT GENERATED ALWAYS AS (json_extract(data, '$.category')) STORED,
    in_stock INTEGER GENERATED ALWAYS AS (
        CASE WHEN json_extract(data, '$.quantity') > 0 THEN 1 ELSE 0 END
    ) STORED
);

-- Index on computed columns — queries as fast as regular columns
CREATE INDEX idx_products_category ON products(category);
CREATE INDEX idx_products_price ON products(price);

-- Query normally — no json_extract needed in WHERE
SELECT name, price FROM products
WHERE category = 'electronics' AND in_stock = 1
ORDER BY price ASC;

7. ORM and Type Safety — Drizzle, Prisma

Writing raw SQL works fine for small projects, but as schemas grow complex, you need an ORM. D1 has first-class support for the two most popular ORMs:

7.1. Drizzle ORM — lightweight, type-safe

// schema.ts — define schema with Drizzle
import { sqliteTable, text, integer, real } from "drizzle-orm/sqlite-core";

export const products = sqliteTable("products", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  name: text("name").notNull(),
  price: real("price").notNull(),
  category: text("category").notNull(),
  createdAt: text("created_at").default("datetime('now')"),
});

export const orders = sqliteTable("orders", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  productId: integer("product_id").references(() => products.id),
  quantity: integer("quantity").notNull(),
  total: real("total").notNull(),
});

// worker.ts — using Drizzle with D1
import { drizzle } from "drizzle-orm/d1";
import { eq, desc, and, gte } from "drizzle-orm";
import * as schema from "./schema";

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const db = drizzle(env.DB, { schema });

    // Type-safe query — IDE autocomplete + compile-time checking
    const expensiveProducts = await db
      .select({
        name: schema.products.name,
        price: schema.products.price,
      })
      .from(schema.products)
      .where(
        and(
          eq(schema.products.category, "electronics"),
          gte(schema.products.price, 100)
        )
      )
      .orderBy(desc(schema.products.price))
      .limit(10);

    // JOIN query — fully type-safe
    const ordersWithProducts = await db
      .select({
        orderId: schema.orders.id,
        productName: schema.products.name,
        quantity: schema.orders.quantity,
        total: schema.orders.total,
      })
      .from(schema.orders)
      .innerJoin(
        schema.products,
        eq(schema.orders.productId, schema.products.id)
      );

    return Response.json({ expensiveProducts, ordersWithProducts });
  },
};

8. Multi-tenant Architecture — Database per Tenant

An architecture where D1 excels: database-per-tenant. With a limit of 50,000 databases per account and no charges for idle databases, you can create a separate database for each user or organization:

graph TB
    subgraph "Traditional Multi-tenant"
        APP1["App Server"] --> SHARED["Shared Database
tenant_id column everywhere
Complex RLS policies"]
    end
    subgraph "D1 Multi-tenant"
        APP2["Worker"] --> ROUTER["Tenant Router"]
        ROUTER --> DB1["D1: tenant-acme
10 MB"]
        ROUTER --> DB2["D1: tenant-globex
50 MB"]
        ROUTER --> DB3["D1: tenant-initech
5 MB"]
        ROUTER --> DB4["D1: tenant-....
50,000 DBs max"]
    end
    style SHARED fill:#ff9800,stroke:#fff,color:#fff
    style ROUTER fill:#e94560,stroke:#fff,color:#fff
    style DB1 fill:#4CAF50,stroke:#fff,color:#fff
    style DB2 fill:#4CAF50,stroke:#fff,color:#fff
    style DB3 fill:#4CAF50,stroke:#fff,color:#fff
    style DB4 fill:#4CAF50,stroke:#fff,color:#fff

Benefits of per-tenant databases:

• Complete isolation: No need for WHERE tenant_id = ? on every query. A bug in one tenant doesn't affect others.
• Easier compliance: Data residency (GDPR) — place EU tenant databases in EU regions. Deleting a tenant = deleting a database, no need for DELETE FROM ... WHERE tenant_id = ? across 50 tables.
• Predictable performance: Large tenants don't slow down small ones. Each database has its own resources.
• Schema flexibility: You can migrate schemas gradually (blue-green migration per tenant).

// Tenant routing — lookup database binding dynamically
export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const tenantId = getTenantFromRequest(request);

    // D1 binding names must be known at deploy time, but you can use
    // the Cloudflare API to manage dynamic bindings
    const dbName = `TENANT_DB_${tenantId}`;
    const db = env[dbName] as D1Database;

    if (!db) {
      return new Response("Tenant not found", { status: 404 });
    }

    const { results } = await db
      .prepare("SELECT * FROM settings")
      .all();

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

9. Pricing — True Scale to Zero

10. Limitations and When NOT to Use D1

11. D1 in the Cloudflare Ecosystem

graph TB
    subgraph "Application Layer"
        W["Workers / Pages Functions"]
    end
    subgraph "Storage Layer"
        D1DB["D1
Relational SQL"]
        KV["Workers KV
Key-Value, edge-cached"]
        R2["R2
Object Storage (files, images)"]
        DO["Durable Objects
Stateful coordination"]
        VE["Vectorize
Vector embeddings"]
        AE["Analytics Engine
Time-series, event logs"]
        HY["Hyperdrive
Connection pool to external DBs"]
    end
    W --> D1DB
    W --> KV
    W --> R2
    W --> DO
    W --> VE
    W --> AE
    W --> HY
    style D1DB fill:#e94560,stroke:#fff,color:#fff
    style W fill:#2c3e50,stroke:#fff,color:#fff
    style KV fill:#f8f9fa,stroke:#e94560,color:#2c3e50
    style R2 fill:#f8f9fa,stroke:#e94560,color:#2c3e50
    style DO fill:#f8f9fa,stroke:#e94560,color:#2c3e50
    style VE fill:#f8f9fa,stroke:#e94560,color:#2c3e50
    style AE fill:#f8f9fa,stroke:#e94560,color:#2c3e50
    style HY fill:#f8f9fa,stroke:#e94560,color:#2c3e50

12. Conclusion

Cloudflare D1 represents a new direction in databases: bringing SQL databases to the edge, zero-config, scale-to-zero. Built on battle-tested SQLite, with Durable Objects ensuring consistency, Sessions API for global read replication, and pricing that's nearly free for small-to-medium workloads — D1 is the ideal choice for edge-first applications on Cloudflare.

However, D1 is not a universal database. The 10 GB limit, single-writer model, and vendor lock-in with Cloudflare Workers are important trade-offs to consider. For systems requiring high write throughput, large datasets, or PostgreSQL-level features — continue using managed PostgreSQL (Neon, Supabase) or Hyperdrive to connect from Workers to external databases. D1 shines in its niche: edge-native, read-heavy applications that need SQL and want maximum simplicity.

References

• Cloudflare D1 Documentation — Cloudflare Docs
• Building D1: a Global Database — Cloudflare Blog
• D1: our quest to simplify databases — Cloudflare Blog
• D1 Pricing — Cloudflare Docs
• D1 Client API Reference — Cloudflare Docs
• Drizzle ORM with Cloudflare D1 — Drizzle Docs
• D1 Sessions API — Cloudflare Docs