Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 36 ยท Storage: R2, KV and D1

Choosing Cloudflare Storage: KV, R2, D1 and Durable Objects

Compare Cloudflare's storage products by data shape, consistency, size and cost, then pick the right one with a decision guide, a diagram and a runnable chooser.

A Worker has no disk, so anything that must survive between requests lives in a storage product reached through a binding. Cloudflare offers several, and each one fits a different shape of data. Choosing wrongly is the most common beginner mistake: people put files in KV, relational data in KV, or counters in D1. This lesson gives you the model to choose well, and the next lessons teach each product.

Cloudflare storage is not available on this site. Code that uses env.KV, env.BUCKET or env.DB is read-only. Runnable examples are stand-ins that model the behavior in plain JavaScript.

The four main products

Workers KV is a global key-value store. You write key -> value and read it from anywhere. Reads are extremely fast and cached at the edge. Writes are eventually consistent: a change may take up to about a minute to be visible in every location. Ideal for configuration, feature flags, redirect tables and cached API results that are read far more than written.

R2 is object storage, compatible with the S3 API, for files of any size: images, videos, backups, build artifacts, user uploads. Its notable feature is no egress fees for data read out of it. Use it when the thing you store is a blob with a name.

D1 is a serverless SQL database built on SQLite. You get tables, indexes, joins, transactions per query batch and migrations. Use it when your data is relational: users, orders, posts, comments.

Durable Objects give you a single, named, strongly consistent object that lives in one place, with its own storage and the ability to hold connections (for example WebSockets). Each object processes requests one at a time, so it is a natural fit for counters, rate limiters, chat rooms, collaborative documents and anything needing coordination.

Others exist and are covered elsewhere: Queues (message passing), Vectorize (vector search), Hyperdrive (connection pooling to an external Postgres or MySQL) and the Cache API (temporary copies of responses).

flowchart TD
  Q["What are you storing?"] --> A{"A file or blob?"}
  A -->|Yes| R2["R2"]
  A -->|No| B{"Relational data, queries, joins?"}
  B -->|Yes| D1["D1"]
  B -->|No| C{"Needs strong consistency or coordination?"}
  C -->|Yes| DO["Durable Objects"]
  C -->|No| KV["Workers KV"]

A decision guide. Real designs often combine two or three of these.

Consistency in plain words

Strong consistency means that once a write finishes, every later read sees it. Eventual consistency means readers may see the old value for a short time.

Product Reads Writes Notes
KV Very fast, edge-cached Eventually consistent (propagation delay) Never use it for a counter or a lock
R2 Strong Strong Objects are replaced atomically
D1 Strong from the primary database; optional read replicas Strong SQLite semantics
Durable Objects Strong, in the object's single location Strong One object = one thread of control

A decision table

Pick by data shape

KV Small values, read often
R2 Files and blobs
D1 Tables and SQL
Durable Objects Coordination

Start with the shape of your data.

1 / 2

A chooser you can run

This stand-in turns the questions into code. It is simplified on purpose: real decisions also weigh price, size and latency.

JS Which storage product?

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Combining products

Real applications mix them. A photo-sharing app might keep photo files in R2, metadata and comments in D1, a hot "popular tags" list cached in KV, and a per-photo like counter in a Durable Object. A good rule: let D1 hold the source of truth for structured data, then use KV or the Cache API to speed up reads, and treat those copies as disposable.

A latency feel

KV reads are fast because values are replicated to the edge on first read. The first read in a location goes to central storage; later reads in that location are served locally until the cache time (cacheTtl) expires. This simulation shows why a freshly written value can appear stale.

JS Why KV reads can be stale

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which product is the best home for user-uploaded profile pictures?

    Files and blobs belong in object storage. R2 is S3-compatible and has no egress fees.
  2. 2. Why is KV a poor choice for a global like counter?

    KV has no atomic increment and propagates writes with delay. A Durable Object serializes updates and is strongly consistent.
  3. 3. Your data has users, posts and comments with relationships. What should you reach for first?

    Relational data with joins and constraints fits D1, which is SQLite semantics at Cloudflare.
  4. 4. What is a sensible role for KV in an app that already has D1?

    Use KV as a read-optimized cache or config layer. Keep the authoritative data in D1.

Summary

  • KV: global key-value, fast reads, eventually consistent writes; for config, flags and read-mostly data.
  • R2: S3-compatible object storage with no egress fees, for files and blobs.
  • D1: SQLite-based SQL database, for relational data.
  • Durable Objects: single-writer, strongly consistent objects for coordination, counters and real-time rooms.
  • Choose by data shape and consistency needs, and combine products with D1 or R2 as the source of truth.

Next: Workers KV: Key-Value Storage