Global read replication·续

Enable read replication via REST API

With the REST API, set read_replication.mode: auto to enable read replication on a D1 database.

For this REST endpoint, you need to have an API token with D1:Edit permission. If you do not have an API token, follow the guide: Create API token.

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/d1/database/{database_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read_replication": {"mode": "auto"}}'

const headers = new Headers({
  "Authorization": `Bearer ${TOKEN}`
});

await fetch ("/v4/accounts/{account_id}/d1/database/{database_id}", {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(
        { "read_replication": { "mode": "auto" } }
    )
 }
)

Disable read replication via REST API

With the REST API, set read_replication.mode: disabled to disable read replication on a D1 database.

For this REST endpoint, you need to have an API token with D1:Edit permission. If you do not have an API token, follow the guide: Create API token.

Note

Disabling read replication takes up to 24 hours for replicas to stop processing requests. Sessions API works with databases that do not have read replication enabled, so it is safe to run code with Sessions API even after disabling read replication.

curl -X PUT "https://api.cloudflare.com/client/v4/accounts/{account_id}/d1/database/{database_id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"read_replication": {"mode": "disabled"}}'

const headers = new Headers({
  "Authorization": `Bearer ${TOKEN}`
});

await fetch ("/v4/accounts/{account_id}/d1/database/{database_id}", {
    method: "PUT",
    headers: headers,
    body: JSON.stringify(
        { "read_replication": { "mode": "disabled" } }
    )
 }
)

Check if read replication is enabled

On the Cloudflare dashboard, check Settings for your D1 database to view if read replication is enabled.

Alternatively, GET D1 database REST endpoint returns if read replication is enabled or disabled.

For this REST endpoint, you need to have an API token with D1:Read permission. If you do not have an API token, follow the guide: Create API token.

curl -X GET "https://api.cloudflare.com/client/v4/accounts/{account_id}/d1/database/{database_id}" \
  -H "Authorization: Bearer $TOKEN"

const headers = new Headers({
  "Authorization": `Bearer ${TOKEN}`
});

const response = await fetch("/v4/accounts/{account_id}/d1/database/{database_id}", {
  method: "GET",
  headers: headers
});

const data = await response.json();
console.log(data.read_replication.mode);
  • Check the read_replication property of the result object
  • "mode": "auto" indicates read replication is enabled
  • "mode": "disabled" indicates read replication is disabled

Read replica locations

Currently, D1 automatically creates a read replica in every supported region, including the region where the primary database instance is located. These regions are:

  • ENAM
  • WNAM
  • WEUR
  • EEUR
  • APAC
  • OC

Note

Read replica locations are subject to change at Cloudflare's discretion.

Observability

To see the impact of read replication and check the how D1 requests are processed by additional database instances, you can use:

  • The meta object within the D1Result return object, which includes new fields:
  • served_by_region
  • served_by_primary
  • The Cloudflare dashboard, where you can view your database metrics breakdown by region that processed D1 requests.

Pricing

D1 read replication is built into D1, so you don’t pay extra storage or compute costs for read replicas. You incur the exact same D1 usage billing with or without replicas, based on rows_read and rows_written by your queries.

Known limitations

There are some known limitations for D1 read replication.

  • Sessions API is only available via the D1 Worker Binding and not yet available via the REST API.

Background information

Replica lag and consistency model

To account for replica lag, it is important to consider the consistency model for D1. A consistency model is a logical framework that governs how a database system serves user queries (how the data is updated and accessed) when there are multiple database instances. Different models can be useful in different use cases. Most database systems provide read committed ↗︎, snapshot isolation ↗︎, or serializable ↗︎ consistency models, depending on their configuration.

Without a consistency model framework

Consider what could happen in a distributed database system without an explicit framework to enforce a consistency model.

Distributed replicas could cause inconsistencies without Sessions API

  1. Your SQL write query is processed by the primary database instance.
  2. You obtain a response acknowledging the write query.
  3. Your subsequent SQL read query goes to a read replica.
  4. The read replica has not yet been updated, so does not contain changes from your SQL write query. The returned results are inconsistent from your perspective.

With Sessions API

When using D1 Sessions API, your queries obtain bookmarks which allows the read replica to only serve sequentially consistent data.

D1 offers sequential consistency when using Sessions API

  1. SQL write query is processed by the primary database instance.
  2. You obtain a response acknowledging the write query. You also obtain a bookmark (100) which identifies the state of the database after the write query.
  3. Your subsequent SQL read query goes to a read replica, and also provides the bookmark (100).
  4. The read replica will wait until it has been updated to be at least as up-to-date as the provided bookmark (100).
  5. Once the read replica has been updated (bookmark 104), it serves your read query, which is now sequentially consistent.

In the diagram, the returned bookmark is bookmark 104, which is different from the one provided in your read query (bookmark 100). This can happen if there were other writes from other client requests that also got replicated to the read replica in between the two write/read queries you executed.

Sessions API provides sequential consistency

D1 read replication offers sequential consistency ↗︎. D1 creates a global order of all operations which have taken place on the database, and can identify the latest version of the database that a query has seen, using bookmarks. It then serves the query with a database instance that is at least as up-to-date as the bookmark passed along with the query to execute.

Sequential consistency has properties such as:

  • Monotonic reads: If you perform two reads one after the other (read-1, then read-2), read-2 cannot read a version of the database prior to read-1.
  • Monotonic writes: If you perform write-1 then write-2, all processes observe write-1 before write-2.
  • Writes follow reads: If you read a value, then perform a write, the subsequent write must be based on the value that was just read.
  • Read my own writes: If you write to the database, all subsequent reads will see the write.

Supplementary information

You may wish to refer to the following resources:

Was this helpful?

YesNo

On this page

Global read replication·续 - 图3Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/d1/best-practices/read-replication/#page","headline":"Global read replication","description":"Reduce read latency and scale throughput by replicating D1 databases across regions globally.","url":"https://developers.cloudflare.com/d1/best-practices/read-replication/","inLanguage":"en","image":"https://developers.cloudflare.com/d1/best-practices/read-replication/og.png?v=22b057957478145b","dateModified":"2026-08-10","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Develop against a D1 database remotely using the Cloudflare dashboard playground. title: Remote development image: https://developers.cloudflare.com/d1/best-practices/remote-development/og.png?v=19cb3ef770f1ffd7

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/d1/llms.txt
Use this file to discover all available pages before exploring further.