Skip to content
Cloudflare Docs

Test D1 read replication

Last reviewed: 28 days ago

In this tutorial, you will create a basic Worker script to test the effect of D1 read replication, and see the difference in the request latency.

Prerequisites

This tutorial assumes you have completed and understood the D1 get started tutorial.

1. Create a Worker

Create a new Worker as the means to query your database.

Terminal window
npm create cloudflare@latest -- <DATABASE_NAME>

2. Create a database located far away

Create a database located far away by specifying a location hint which is far away from the region you are located in.

Terminal window
npx wrangler d1 create <DATABASE_NAME> --location=apac
✅ 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 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 tutorial.

  1. Copy the following code and save it as a schema.sql file in the Worker directory you created in step 1:

    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.

    Terminal window
    npx wrangler d1 execute <DATABASE_NAME> --remote --file=./schema.sql

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.

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

Terminal window
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.