[D1] D1 RR Documentation (#20922)

Oxyjun · vy-ton · lambrospetrou · web-flow · commit 205760f777ab · 2025-04-09T23:35:27.000+01:00
D1 read replication docs

---------

Co-authored-by: Vy Ton &lt;vy@cloudflare.com&gt;
Co-authored-by: Lambros Petrou &lt;lambrospetrou@gmail.com&gt;
Co-authored-by: Harshil Agrawal &lt;18901032+harshil1712@users.noreply.github.com&gt;
diff --git a/public/images/d1/consistency-with-sessions-api.png b/public/images/d1/consistency-with-sessions-api.png
diff --git a/public/images/d1/consistency-without-sessions-api.png b/public/images/d1/consistency-without-sessions-api.png
diff --git a/public/images/d1/d1-read-replication-concept.png b/public/images/d1/d1-read-replication-concept.png
diff --git a/src/content/apps/index.yaml b/src/content/apps/index.yaml
@@ -340,3 +340,18 @@
   languages: [TypeScript]
   cloudflare: false
   updated: 2024-10-07
+- link: https://github.com/harshil1712/e-com-d1
+  id: E-commerce Store
+  description: An application to showcase D1 read replication in the context of an online store.
+  tags: []
+  products: [Workers, D1]
+  languages: [TypeScript]
+  cloudflare: true
+  updated: 2025-02-27
+- link: https://github.com/cloudflare/templates/tree/main/d1-starter-sessions-api-template
+  id: Starter code for D1 Sessions API
+  description: An introduction to D1 Sessions API. This demo simulates purchase orders administration.
+  products: [Workers, D1]
+  languages: [TypeScript]
+  cloudflare: true
+  updated: 2025-03-31
diff --git a/src/content/changelog/d1/2025-04-10-d1-read-replication-beta.mdx b/src/content/changelog/d1/2025-04-10-d1-read-replication-beta.mdx
@@ -0,0 +1,34 @@
+---
+title: D1 Read Replication Public Beta
+description: Use D1 Sessions API to leverage read replication.
+products:
+  - d1
+  - workers
+date: 2025-04-10T06:00:00Z
+hidden: true
+---
+
+D1 read replication is available in public beta to help lower average latency and increase overall throughput for read-heavy applications like e-commerce websites or content management tools.
+
+Workers can leverage read-only database copies, called read replicas, by using D1 [Sessions API](/d1/best-practices/read-replication). A session encapsulates all the queries from one logical session for your application. For example, a session may correspond to all queries coming from a particular web browser session. With Sessions API, D1 queries in a session are guaranteed to be [sequentially consistent](/d1/best-practices/read-replication/#replica-lag-and-consistency-model) to avoid data consistency pitfalls. D1 [bookmarks](/d1/reference/time-travel/#bookmarks) can be used from a previous session to ensure logical consistency between sessions.
+
+```ts
+// retrieve bookmark from previous session stored in HTTP header
+const bookmark = request.headers.get('x-d1-bookmark') ?? 'first-unconstrained';
+
+const session = env.DB.withSession(bookmark)
+const result = await session
+	.prepare(`SELECT * FROM Customers WHERE CompanyName = 'Bs Beverages'`)
+	.run()
+// store bookmark for a future session
+response.headers.set('x-d1-bookmark', session.getBookmark() ?? "")
+```
+
+Read replicas are automatically created by Cloudflare (currently one in each supported [D1 region](/d1/best-practices/read-replication/#read-replica-locations)), are active/inactive based on query traffic, and are transparently routed to by Cloudflare at no additional cost.
+
+To checkout D1 read replication, deploy the following Worker code using Sessions API, which will prompt you to create a D1 database and enable read replication on said database.
+
+   [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/templates/tree/staging/d1-starter-sessions-api)
+
+To learn more about how read replication was implemented, go to our [blog post](https://blog.cloudflare.com/d1-read-replication-beta).
+
diff --git a/src/content/docs/d1/best-practices/read-replication.mdx b/src/content/docs/d1/best-practices/read-replication.mdx
diff --git a/src/content/docs/d1/configuration/data-location.mdx b/src/content/docs/d1/configuration/data-location.mdx
@@ -9,13 +9,13 @@ Learn how the location of data stored in D1 is determined, including where the l
 
 ## Automatic (recommended)
 
-By default, D1 will automatically create your database in a location close to where you issued the request to create a database. In most cases this allows D1 to choose the optimal location for your database on your behalf.
+By default, D1 will automatically create your primary database instance in a location close to where you issued the request to create a database. In most cases this allows D1 to choose the optimal location for your database on your behalf.
 
 ## Provide a location hint
 
-Location hint is an optional parameter you can provide to indicate your desired geographical location for your database.
+Location hint is an optional parameter you can provide to indicate your desired geographical location for your primary database instance.
 
-You may want to explicitly provide a location hint in cases where the majority of your writes to a specific database come from a different location than where you are creating the database from. location hints can be useful when:
+You may want to explicitly provide a location hint in cases where the majority of your writes to a specific database come from a different location than where you are creating the database from. Location hints can be useful when:
 
 - Working in a distributed team.
 - Creating databases specific to users in specific locations.
@@ -33,9 +33,7 @@ Providing a location hint does not guarantee that D1 runs in your preferred loca
 ### Use Wrangler
 
 :::note
-
 To install Wrangler, the command-line interface for D1 and Workers, refer to [Install and Update Wrangler](/workers/wrangler/install-and-update/).
-
 :::
 
 To provide a location hint when creating a new database, pass the `--location` flag with a valid location hint:
@@ -70,3 +68,11 @@ D1 supports the following location hints:
 :::caution
 D1 location hints are not currently supported for South America (`sam`), Africa (`afr`), and the Middle East (`me`). D1 databases do not run in these locations.
 :::
+
+## Read replica locations
+
+With read replication enabled, D1 creates and distributes read-only copies of the primary database instance around the world. This reduces the query latency for users located far away from the primary database instance.
+
+When using D1 read replication, D1 automatically creates a read replica in [every available region](/d1/configuration/data-location#available-location-hints), including the region where the primary database instance is located.
+
+Refer to [D1 read replication](/d1/best-practices/read-replication/) for more information.
diff --git a/src/content/docs/d1/configuration/index.mdx b/src/content/docs/d1/configuration/index.mdx
@@ -2,7 +2,7 @@
 title: Configuration
 pcx_content_type: navigation
 sidebar:
-  order: 8
+  order: 9
   group:
     hideIndex: true
 ---
diff --git a/src/content/docs/d1/d1-api.mdx b/src/content/docs/d1/d1-api.mdx
@@ -3,5 +3,5 @@ pcx_content_type: navigation
 title: REST API
 external_link: /api/resources/d1/subresources/database/methods/create/
 sidebar:
-  order: 6
+  order: 7
 ---
diff --git a/src/content/docs/d1/demos.mdx b/src/content/docs/d1/demos.mdx
@@ -2,14 +2,26 @@
 pcx_content_type: navigation
 title: Demos and architectures
 sidebar:
-  order: 12
+  order: 13
 
 ---
 
 import { ExternalResources, GlossaryTooltip, ResourcesBySelector } from "~/components"
 
 Learn how you can use D1 within your existing application and architecture.
 
+## Featured Demos
+
+- [Starter code for D1 Sessions API](https://github.com/cloudflare/templates/tree/main/d1-starter-sessions-api-template): An introduction to D1 Sessions API. This demo simulates purchase orders administration.
+
+  [![Deploy to Cloudflare](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/cloudflare/templates/tree/main/d1-starter-sessions-api-template)
+
+:::note[Tip: Place your database further away for the read replication demo]
+To simulate how read replication can improve a worst case latency scenario, select your primary database location to be in a farther away region (one of the deployment steps).
+
+You can find this in the **Database location hint** dropdown.
+:::
+
 ## Demos
 
 Explore the following <GlossaryTooltip term="demo application">demo applications</GlossaryTooltip> for D1.
diff --git a/src/content/docs/d1/examples/index.mdx b/src/content/docs/d1/examples/index.mdx
@@ -4,7 +4,7 @@ hideChildren: false
 pcx_content_type: navigation
 title: Examples
 sidebar:
-  order: 10
+  order: 11
   group:
     hideIndex: true
 ---
diff --git a/src/content/docs/d1/get-started.mdx b/src/content/docs/d1/get-started.mdx
@@ -6,16 +6,7 @@ sidebar:
   order: 2
 ---
 
-import {
-	Render,
-	PackageManagers,
-	Steps,
-	FileTree,
-	Tabs,
-	TabItem,
-	TypeScriptExample,
-	WranglerConfig
-} from "~/components";
+import { Render, PackageManagers, Steps, FileTree, Tabs, TabItem, TypeScriptExample, WranglerConfig } from "~/components";
 
 This guide instructs you through:
 
diff --git a/src/content/docs/d1/observability/index.mdx b/src/content/docs/d1/observability/index.mdx
@@ -2,7 +2,7 @@
 title: Observability
 pcx_content_type: navigation
 sidebar:
-  order: 9
+  order: 10
   group:
     hideIndex: true
 ---
diff --git a/src/content/docs/d1/platform/index.mdx b/src/content/docs/d1/platform/index.mdx
@@ -2,7 +2,7 @@
 pcx_content_type: navigation
 title: Platform
 sidebar:
-  order: 12
+  order: 13
   group:
     hideIndex: true
 ---
diff --git a/src/content/docs/d1/platform/limits.mdx b/src/content/docs/d1/platform/limits.mdx
@@ -15,7 +15,7 @@ import { Render } from "~/components";
 | Maximum storage per account                                                                                         | 250 GB (Workers Paid)[^1] / 5 GB (Free)           |
 | [Time Travel](/d1/reference/time-travel/) duration (point-in-time recovery)                                         | 30 days (Workers Paid) / 7 days (Free)            |
 | Maximum Time Travel restore operations                                                                              | 10 restores per 10 minute (per database)          |
-| Queries per Worker invocation (read [subrequest limits](/workers/platform/limits/#how-many-subrequests-can-i-make)) | 50 (Bundled) / 1000 (Unbound)                     |
+| Queries per Worker invocation (read [subrequest limits](/workers/platform/limits/#how-many-subrequests-can-i-make)) | 50 (Free) / 1000 (Paid)                     |
 | Maximum number of columns per table                                                                                 | 100                                               |
 | Maximum number of rows per table                                                                                    | Unlimited (excluding per-database storage limits) |
 | Maximum string, `BLOB` or table row size                                                                            | 2,000,000 bytes (2 MB)                            |
diff --git a/src/content/docs/d1/reference/index.mdx b/src/content/docs/d1/reference/index.mdx
@@ -2,7 +2,7 @@
 pcx_content_type: navigation
 title: Reference
 sidebar:
-  order: 13
+  order: 14
   group:
     hideIndex: true
 ---
diff --git a/src/content/docs/d1/reference/migrations.mdx b/src/content/docs/d1/reference/migrations.mdx
@@ -20,6 +20,12 @@ Currently, the migrations system aims to be simple yet effective. With the curre
 
 Every migration file in the `migrations` folder has a specified version number in the filename. Files are listed in sequential order. Every migration file is an SQL file where you can specify queries to be run.
 
+:::note[Binding name vs Database name]
+When running a migration script, you can use either the binding name or the database name.
+
+However, the binding name can change, whereas the database name cannot. Therefore, to avoid accidentally running migrations on the wrong binding, you may wish to use the database name for D1 migrations.
+:::
+
 ## Wrangler customizations
 
 By default, migrations are created in the `migrations/` folder in your Worker project directory. Creating migrations will keep a record of applied migrations in the `d1_migrations` table found in your database.
diff --git a/src/content/docs/d1/reference/time-travel.mdx b/src/content/docs/d1/reference/time-travel.mdx
@@ -5,6 +5,8 @@ sidebar:
   order: 2
 ---
 
+import { GlossaryTooltip} from "~/components"
+
 Time Travel is D1's approach to backups and point-in-time-recovery, and allows you to restore a database to any minute within the last 30 days.
 
 - You do not need to enable Time Travel. It is always on.
@@ -23,13 +25,14 @@ To understand which storage subsystem your database uses, run `wrangler d1 info
 
 ## Bookmarks
 
-Time Travel introduces the concept of a "bookmark" to D1. A bookmark represents the state of a database at a specific point in time, and is effectively an append-only log.
+Time Travel leverages D1's concept of a <GlossaryTooltip term="bookmark"> bookmark </GlossaryTooltip> to restore to a point in time. 
 
-- Bookmarks are lexicographically sortable. Sorting orders a list of bookmarks from oldest-to-newest.
 - Bookmarks older than 30 days are invalid and cannot be used as a restore point.
 - Restoring a database to a specific bookmark does not remove or delete older bookmarks. For example, if you restore to a bookmark representing the state of your database 10 minutes ago, and determine that you needed to restore to an earlier point in time, you can still do so.
+- Bookmarks are lexicographically sortable. Sorting orders a list of bookmarks from oldest-to-newest.
+- Bookmarks can be derived from a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) (seconds since Jan 1st, 1970), and conversion between a specific timestamp and a bookmark is deterministic (stable).
 
-Bookmarks can be derived from a [Unix timestamp](https://en.wikipedia.org/wiki/Unix_time) (seconds since Jan 1st, 1970), and conversion between a specific timestamp and a bookmark is deterministic (stable).
+Bookmarks are also leveraged by [Sessions API](/d1/best-practices/read-replication/#sessions-api-examples) to ensure sequential consistency within a Session.
 
 ## Timestamps
 
diff --git a/src/content/docs/d1/sql-api/index.mdx b/src/content/docs/d1/sql-api/index.mdx
@@ -2,7 +2,7 @@
 title: SQL API
 pcx_content_type: navigation
 sidebar:
-  order: 5
+  order: 6
   group:
     hideIndex: true
 ---
diff --git a/src/content/docs/d1/tutorials/index.mdx b/src/content/docs/d1/tutorials/index.mdx
@@ -4,7 +4,7 @@ pcx_content_type: navigation
 title: Tutorials
 hideChildren: true
 sidebar:
-  order: 11
+  order: 12
 
 ---
 
diff --git a/src/content/docs/d1/tutorials/using-read-replication-for-e-com/index.mdx b/src/content/docs/d1/tutorials/using-read-replication-for-e-com/index.mdx
diff --git a/src/content/docs/d1/worker-api/d1-database.mdx b/src/content/docs/d1/worker-api/d1-database.mdx
diff --git a/src/content/docs/d1/worker-api/index.mdx b/src/content/docs/d1/worker-api/index.mdx
diff --git a/src/content/glossary/d1.yaml b/src/content/glossary/d1.yaml
