[D1] D1 RR Documentation

src/content/apps/index.yaml

@@ -340,3 +340,11 @@
   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

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.

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
 ---

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
 ---

src/content/docs/d1/demos.mdx

@@ -2,7 +2,7 @@
 pcx_content_type: navigation
 title: Demos and architectures
 sidebar:
-  order: 12
+  order: 13
 
 ---
 

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
 ---

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:
 

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
 ---

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
 ---

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
 ---

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
 

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
 ---

src/content/docs/d1/tutorials/index.mdx

@@ -4,7 +4,7 @@ pcx_content_type: navigation
 title: Tutorials
 hideChildren: true
 sidebar:
-  order: 11
+  order: 12
 
 ---
 

src/content/docs/d1/tutorials/test-read-replication/index.mdx

@@ -0,0 +1,165 @@
+---
+updated: 2025-03-04
+difficulty: Beginner
+content_type: Tutorial
+pcx_content_type: tutorial
+title: Test D1 read replication
+products:
+  - D1
+languages:
+  - JavaScript
+  - TypeScript
+  - SQL
+---
+
+import { Render, Steps, Tabs, TabItem, FileTree } from "~/components";
+
+In this tutorial, you will create a basic Worker script to test the effect of [D1 read replication](/d1/best-practices/read-replication/), and see the difference in the request latency.
+
+## Prerequisites
+
+This tutorial assumes you have completed and understood the [D1 get started](/d1/get-started/) tutorial.
+
+## 1. Create a Worker
+
+Create a new Worker as the means to query your database.
+
+```sh
+npm create cloudflare@latest -- <DATABASE_NAME>
+```
+
+## 2. Create a database located far away
+
+Create a database located far away by specifying a [location hint](/d1/configuration/data-location/) which is far away from the region you are located in.
+
+```sh
+npx wrangler d1 create <DATABASE_NAME> --location=apac
+```
+```sh output
+✅ Successfully created DB '<DATABASE_NAME>' in region APAC
+Created your new D1 database.
+
+{
+  "d1_databases": [
+    {
+      "binding": "DB",
+      "database_name": "<DATABASE_NAME>",
+      "database_id": "<DATABASE_ID>"
+    }
+  ]
+}
+```
+
+This creates a new D1 database and outputs the [binding](/workers/runtime-apis/bindings/) configuration needed in the next step.
+
+## 3. Bind your D1 database to your Worker
+
+Modify your `wrangler.jsonc` file to include the output of the CLI to bind your D1 database to your Worker.
+
+## 4. Populate the D1 database
+
+Populate your database with the table from the [D1 get started](/d1/get-started/) tutorial.
+
+<Steps>
+1. Copy the following code and save it as a `schema.sql` file in the Worker directory you created in step 1:
+
+    ```sql
+    DROP TABLE IF EXISTS Customers;
+    CREATE TABLE IF NOT EXISTS Customers (CustomerId INTEGER PRIMARY KEY, CompanyName TEXT, ContactName TEXT);
+    INSERT INTO Customers (CustomerID, CompanyName, ContactName) VALUES (1, 'Alfreds Futterkiste', 'Maria Anders'), (4, 'Around the Horn', 'Thomas Hardy'), (11, 'Bs Beverages', 'Victoria Ashworth'), (13, 'Bs Beverages', 'Random Name');
+    ```
+
+2. Initialize your database to run remotely.
+
+    ```sh
+    npx wrangler d1 execute <DATABASE_NAME> --remote --file=./schema.sql
+    ```
+</Steps>
+
+## 5. Write a Worker file which queries the table
+
+Write a Worker file which queries the table and outputs both the results with the query latency.
+
+```js
+export default {
+  async fetch(request, env) {
+    const { pathname } = new URL(request.url);
+    const companyName1 = `Bs Beverages`;
+    const stmt = env.DB.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`);
+    const session = env.DB.withSession("first-unconstrained");
+
+    if (pathname === `/run`) {
+    const tsStart1 = Date.now();
+    const { results, meta } = await stmt.bind(companyName1).run();
+    const d1Duration1 = Date.now() - tsStart1;
+    return Response.json({ results, meta, d1Duration1 });
+
+    } else if (pathname === `/withsession`) {
+    const tsStart2 = Date.now();
+    const { results, meta } = await session.prepare(`SELECT * FROM Customers WHERE CompanyName = ?`).bind(companyName1).run();
+    const d1Duration2 = Date.now() - tsStart2;
+    return Response.json({ results, meta, d1Duration2 });
+    }
+    return new Response(
+    `Welcome to the D1 read replication demo!
+
+  Add one of the following slugs below to see the effects of using D1 read replication.
+
+  \n/run - Queries the table without using read replication
+
+  \n/withsession - Queries the table using read replication (using "first-unconstrained")
+
+  \nUse the two options to compare the difference in query latency.`
+    );
+  }
+  };
+```
+
+## 6. Enable read replication
+
+Use the REST API to enable read replication on your D1 database.
+
+Run the following `curl` command on your terminal, with the details of your account ID and database ID.
+
+```curl
+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"}}'
+```
+
+## 7. Deploy Worker
+
+Deploy your Worker.
+
+```sh
+npx wrangler deploy
+```
+
+## 8. Compare query latency
+
+Once deployed, you can compare the query latency when using read replication.
+
+- Use the `/run` URL to send a read query without read replication.
+- Use the `/withsession` URL to send a read query with read replication.
+
+For both queries, the Worker script returns the `meta` object, which contains:
+
+- `served_by_primary`: indicates whether the query was served by the primary database instance
+- `served_by_region`: shows the location of the database instance that processed the query
+
+The `d1Duration` variable shows the whole round-trip latency.
+
+## Summary
+
+By completing this tutorial, you have:
+
+1. Created a D1 database using a location hint.
+2. Created a Worker script which uses read replication.
+3. Deployed the Worker to test the difference in query latency when using read replication.
+
+## Related resources
+
+- [D1 read replication](/d1/best-practices/read-replication)
+- [D1 Sessions Workers Binding API](/d1/worker-api/d1-database#withsession)
+- [D1 read replication demo application](/d1/demos/)