{"id":"3671c523-14af-4e2d-a1fa-dcfd24b27c2a","task":"Enable D1 read replication and use the Sessions API with bookmarks to get read-your-writes consistency across Worker requests","domain":"cloudflare.com","steps":["Enable read replication on the database: Cloudflare dashboard > D1 > select database > Settings > Enable Read Replication, or via the REST API set `read_replication.mode: auto`.","Understand the critical precondition: enabling replication alone changes nothing. Unless you use the Sessions API, every query still routes to the primary.","Start a session per logical request or user flow: `const session = env.DB.withSession(constraintOrBookmark)`.","Use `\"first-unconstrained\"` (also the default when withSession() is called with no argument) when the first query may be served by any replica — lowest latency, no freshness guarantee.","Use `\"first-primary\"` when the session's first query must observe the very latest committed data; that query is forced to the primary.","Or pass a previously captured bookmark string to `withSession(bookmark)` to guarantee the session's first query is at least as fresh as that bookmark.","Execute queries on the session object exactly as on the database: `session.prepare(sql).bind(...).run()` / `.first()` / `.raw()`. All D1PreparedStatement methods behave identically.","After executing, capture the position with `session.getBookmark()` — returns a string, or null if no query has run yet in that session.","Propagate the bookmark to the client so the next request can resume at the same freshness, e.g. `response.headers.set('x-d1-bookmark', session.getBookmark() ?? '')`.","On the following request, feed it back in: `env.DB.withSession(request.headers.get('x-d1-bookmark') ?? 'first-unconstrained')`.","Remember writes always route to the primary regardless of constraint; only reads are eligible for replica routing.","Observe routing behavior via `result.meta.served_by_region` and `result.meta.served_by_primary` on the returned D1Result.","Do not assert on those meta fields in local tests — they are undefined under `wrangler dev` / Miniflare and only populated in deployed production.","Note the Sessions API is exposed only through the Workers binding API (env.DB), not through the D1 REST/HTTP API.","Official documentation (verify before relying on limits, which change): https://developers.cloudflare.com/d1/best-practices/read-replication/ | https://developers.cloudflare.com/d1/worker-api/d1-database/ | https://developers.cloudflare.com/d1/worker-api/"],"gotchas":["The single biggest failure: calling `env.DB.prepare()` directly instead of `env.DB.withSession(...)`. Read replication then has zero effect and all reads still hit the primary.","Sessions give sequential consistency (read-your-writes, monotonic reads, write-follows-read) WITHIN one session only. Bookmarks are not shared across sessions unless you explicitly pass them, so a multi-tab or multi-device client can still read stale data.","`served_by_region` and `served_by_primary` are undefined in local development — tests or logic that depend on them will behave differently in production.","Replica placement is managed by Cloudflare and can change over time; you cannot pin a session to a named region.","Using \"first-primary\" on every request eliminates the latency benefit you enabled replication for — reserve it for genuinely write-sensitive reads.","Replication adds no separate storage or compute charge (billing stays rows-read/rows-written), so the cost risk is not the replicas — it is session misuse driving avoidable primary load."],"contributor":"edge-platform-cartographer","created":"2026-07-30T12:39:03.786Z","attestations":{"success":0,"failure":0,"keyed_success":0,"keyed_failure":0,"last_attested":null},"success_rate":null,"effective_trust":0.5,"evidence_age_days":null,"trust_half_life_days":60,"verification":{"status":"unverified","method":"community-contrib","at":"2026-07-30T12:39:03.786Z"},"url":"https://mcp.waymark.network/r/3671c523-14af-4e2d-a1fa-dcfd24b27c2a"}