Cloudflare / 02
Where
data lives.
Each store makes a different promise about what a reader elsewhere sees after a write. Write from one place, read from another, and find out which answers each one allows.
Illustration Two readers, one changed value
Reader B reads, reader A writes and is acknowledged, then B reads again.
- Workers KV. B keeps getting its cached answer, even a cached “missing” for a key read before it existed, until the cache refreshes, which can take 60 seconds or more.
- R2. Through a binding, B gets the new object right after the acknowledged write. Through a cached URL it gets the old one until the copy is purged.
- D1. With replication off, or reading the primary directly, B gets the new title. A new unconstrained session may land on a replica that is behind. A read that continues with A’s bookmark waits until the update reaches the replica, then returns the new title.
-
Durable Object. A and B both address
room:heronand agree. Change B’s name toroom:foxand B reaches a different object with its own state.
- Request or response
- Call through a binding
- Stale copy or a replica behind
- Two locations are two places a reader can be, not a map
Read the mechanism
R2: the bytes
An object is a file’s bytes plus metadata under a key. Reads,
writes, deletes and lists are strongly consistent: once a write
returns, every reader through R2 gets the new object. A response
cached on a custom domain is not R2; purge it, or give the new
version a new key. Public access through r2.dev is
rate-limited and meant for development; caching needs a custom
domain.
Workers KV: the read-mostly value
KV is eventually consistent. A change can take 60 seconds or more to be visible in other locations, and a lookup that found nothing is cached too, so a key you just created can read as missing. Do not use it for anything two readers must agree on now: a seat count, a counter, a permission.
D1: the records
Every write goes to the primary. Read replication is off unless you turn it on, and without the Sessions API every query runs on the primary. A session started with no constraint may run its first query anywhere. A session continued with a bookmark, an opaque token from an earlier query, waits for a replica at least as new as that bookmark.
Durable Objects: the coordinator
Every request for one name in one namespace reaches the same object, with its own private, strongly consistent storage. A different name is a different object, and only that object reads or writes its storage.
Pick by what you keep
- Photo bytes: R2
- A file has a key and bytes. Put it in an R2 bucket and keep its searchable details in a database.
- Searchable records: D1
- Titles, owners, and albums fit tables. D1 lets the application query and join them with SQL.
- Read-mostly settings: Workers KV
- A value looked up by key, read often, and changed rarely fits KV, as long as a reader may see the old value for a while after a change.
- A shared live room: Durable Objects
- A room needs one place where its decisions are made. A Durable Object keeps the room’s code and its storage together, under the room’s name.
Sources and limits
Cloudflare pages used
-
R2 consistency
and
public buckets : strongly consistent object operations; stale cached custom-domain
responses;
r2.devfor development. - How KV works : eventual consistency, 60 seconds or more, cached negative lookups.
- D1 and D1 read replication : writes on the primary; without the Sessions API all queries on the primary; unconstrained sessions; bookmarked reads wait.
- What are Durable Objects? : one object per name, private storage.
Documented and illustrated
- Documented: which values each store permits B to read after A’s acknowledged write, the 60 seconds or more for KV, and the waiting bookmarked read.
-
Illustration: the two locations, every key, value
and name (
gallery:theme, light and dark,photos/heron.jpg, photos A and B, the titles Heron and Grey heron, the bookmarkbm·7f3a,room:heron,room:foxand their revisions), and the order the reader chooses. The refresh, the purge and the delivery happen when you press them, not on a clock.
Left out on purpose
- Pricing, latency, throughput, capacity, and size limits, including object, value, and database size limits.
- Whether a KV write is visible at once where it was made. Cloudflare says it usually is, and advises not relying on it, so the instrument never reads A’s own value back.
- Hyperdrive, Analytics Engine, and other stores outside this guide.