Read Replication

Read Replication

D1 Manager provides visibility and control over Cloudflare D1's Read Replication feature, helping you improve read performance with globally distributed replicas.

Overview

D1 Read Replication creates multiple copies of your database across Cloudflare's global network. This provides:

• Lower latency - Reads served from the nearest replica
• Higher throughput - Distributed load across multiple replicas
• Sequential consistency - Guaranteed with Sessions API

D1 Manager allows you to:

• View read replication status for each database
• Enable/disable read replication
• See which region served your queries
• Learn about the Sessions API for your own applications

Accessing Read Replication

1. Select a database from the database list
2. Click the Replication tab in the database view
3. View status, toggle replication, and access documentation

Database List Indicator

Databases with read replication enabled show a Replicated badge with a globe icon next to the version badge in the database list.

Replication Status

The Replication panel shows:

Current Status

• Enabled - Reads may be served by global replicas
• Disabled - All queries go to the primary database

Toggle Control

Click Enable or Disable to change the replication mode.

Note: Disabling read replication takes up to 24 hours for replicas to stop processing requests.

Replica Locations

When enabled, D1 automatically creates replicas in these regions:

Code	Region
ENAM	Eastern North America
WNAM	Western North America
WEUR	Western Europe
EEUR	Eastern Europe
APAC	Asia Pacific
OC	Oceania

Query Console Serving Info

When executing queries in the Query Console, you'll see which region served the query:

• Server icon - Query served by primary database
• Globe icon (blue) - Query served by a read replica
• Region code - The specific region that served the query (e.g., WEUR, APAC)

Example: WEUR (replica) indicates the query was served by the Western Europe replica.

Sessions API

For Your Own Applications

When using read replication in your own Cloudflare Workers applications, use the Sessions API to ensure sequential consistency:

// Start a session from the primary (latest data)
const session = env.DB.withSession('first-primary');
const result = await session
  .prepare('SELECT * FROM users')
  .run();

// Get the bookmark for future sessions
const bookmark = session.getBookmark();

Session Modes

Mode	Description	Use Case
first-primary	Start from primary database	Need latest data
first-unconstrained	Start from any replica	Read-only, speed critical
<bookmark>	Continue from specific state	Cross-request consistency

Example: Maintaining Consistency

// Request 1: Get user and store bookmark
const session = env.DB.withSession('first-primary');
const user = await session.prepare('SELECT * FROM users WHERE id = ?').bind(1).first();
response.headers.set('x-d1-bookmark', session.getBookmark() ?? '');

// Request 2: Use bookmark for consistency
const bookmark = request.headers.get('x-d1-bookmark') ?? 'first-unconstrained';
const session = env.DB.withSession(bookmark);
const orders = await session.prepare('SELECT * FROM orders WHERE user_id = ?').bind(1).all();

API Endpoints

Get Database Info (includes replication status)

GET /api/databases/:dbId/info

Response:

{
  "success": true,
  "result": {
    "uuid": "...",
    "name": "my-database",
    "read_replication": {
      "mode": "auto"
    }
  }
}

Set Read Replication Mode

PUT /api/databases/:dbId/replication
Content-Type: application/json

Body:

{
  "mode": "auto"
}

Mode	Description
auto	Enable read replication
disabled	Disable read replication

Response:

{
  "success": true,
  "result": {
    "uuid": "...",
    "read_replication": {
      "mode": "auto"
    }
  }
}

Limitations

REST API vs Sessions API

D1 Manager accesses databases via REST API, which has the following limitations:

• Sessions API not available - Sessions API only works with D1 Worker bindings
• No bookmark passing - Cannot pass bookmarks between REST API requests
• Query routing - REST API queries may be routed to any available instance

For full read replication benefits with sequential consistency, use the Sessions API in your own Cloudflare Workers applications.

Propagation Time

• Enabling read replication: Replicas created within minutes
• Disabling read replication: Takes up to 24 hours for replicas to stop serving requests

Best Practices

When to Enable Read Replication

Enable read replication when you have:

• High read volume from globally distributed users
• Read-heavy workloads where eventual consistency is acceptable
• Applications that can use Sessions API for consistency

When to Keep Disabled

Keep read replication disabled when:

• Your application requires strict consistency without Sessions API
• All users are in a single geographic region
• Write-heavy workloads (all writes go to primary)

Using with Time Travel

Read Replication and Time Travel both use bookmarks:

• Time Travel: Bookmarks identify database state for point-in-time recovery
• Sessions API: Bookmarks ensure sequential consistency across replicas

The same bookmark can be used for both purposes.

Pricing

D1 read replication is built into D1 with no extra storage or compute costs. You incur the same D1 usage billing based on rows_read and rows_written.

Troubleshooting

"Failed to update read replication"

• Verify your API token has D1 Edit permission
• Check that the database exists and is not a protected system database
• Wait if you recently changed the replication mode (propagation delay)

Query showing wrong region

• Region shown is based on routing, which may vary
• With read replication enabled, different requests may hit different replicas
• Use Sessions API in your own applications for consistent routing

Slow replica updates

• Replicas are updated asynchronously
• Write to primary, then read from replica may show stale data
• Use Sessions API with bookmarks for read-your-writes consistency

See Also

• Time Travel - Point-in-time recovery using bookmarks
• Query Console - Execute queries and see serving info
• Database Management - Manage database settings
• Cloudflare D1 Read Replication Docs

---

Need Help? See Troubleshooting or open an issue.