Which storage should I use? KV vs D1 vs R2 vs DO vs Hyperdrive

Cloudflare gives you five very different ways to store data, and they all sit behind your Worker. Picking the wrong one makes everything harder; picking the right one makes your code short and fast. This guide turns the choice into a few yes/no questions.

Here is the whole cast on one stage: the Worker is the brain, and each store plays one role. KV is the cache, D1 is the SQL table, R2 is the file shelf, Durable Objects is the single source of truth, and Hyperdrive is the fast lane to a database you already own.

Start at the top and follow the answers. Each branch lands on exactly one product. You can always combine several later, but for any single piece of data this tree gives you a clear default.

One card per store, with the one-line rule for when to reach for it.

A binding is a name you declare in wrangler.jsonc that shows up as env.SOMETHING inside your Worker. Here is the smallest real snippet for each store — notice how different the access patterns are.

1. KV — get / put a value

   Look up by key; values are strings (or streams). Optional TTL auto-expires the key.

   jscontent_copyCopy

   // wrangler.jsonc -> { "kv_namespaces": [{ "binding": "KV", "id": "..." }] }
   const cached = await env.KV.get("user:42");
   await env.KV.put("user:42", JSON.stringify(user), { expirationTtl: 3600 });

2. D1 — prepared SQL query

   Write SQL with ? placeholders, bind() the values, then .all() for rows.

   jscontent_copyCopy

   // wrangler.jsonc -> { "d1_databases": [{ "binding": "DB", "database_name": "app" }] }
   const { results } = await env.DB
     .prepare("SELECT * FROM orders WHERE city = ?")
     .bind("Taipei")
     .all();

3. R2 — store / fetch an object

   put() a file by key, get() it back as an object whose .body is a stream.

   jscontent_copyCopy

   // wrangler.jsonc -> { "r2_buckets": [{ "binding": "BUCKET", "bucket_name": "files" }] }
   await env.BUCKET.put("invoice.pdf", request.body);
   const object = await env.BUCKET.get("invoice.pdf");
   return new Response(object.body);

4. Durable Objects — call a stub

   getByName() returns the ONE instance for that name; call its methods directly over RPC. Every caller hits the same object.

   jscontent_copyCopy

   // wrangler.jsonc -> durable_objects: { "name": "ROOM", "class_name": "Room" }
   const stub = env.ROOM.getByName("room-42");
   const count = await stub.increment(); // strongly consistent

5. Hyperdrive — connection string

   Read env.HYPERDRIVE.connectionString and connect with a normal pg client; pooling and caching happen for you.

   jscontent_copyCopy

   // wrangler.jsonc -> { "hyperdrive": [{ "binding": "HYPERDRIVE", "id": "..." }] }
   import { Client } from "pg";
   
   const client = new Client({ connectionString: env.HYPERDRIVE.connectionString });
   await client.connect();
   const { rows } = await client.query("SELECT * FROM products LIMIT 10");

Three ideas decide most of these picks: consistency, relational vs key-value, and object storage. Get these and the tree becomes obvious.

Use X when…

• Use KV when: tiny values are read far more than written and ~60s global sync is fine (cache, config, sessions).
• Use D1 when: you need relational tables and SQL queries (JOIN/WHERE/ORDER BY) in a Cloudflare-native database.
• Use R2 when: you store big files — images, video, PDFs, backups — and want zero egress fees.
• Use Durable Objects when: one shared piece of state must be strongly consistent and coordinated (counters, rooms, locks).
• Use Hyperdrive when: you already run Postgres/MySQL elsewhere and just want it fast from Workers — no migration.

• KV: read-heavy, eventually consistent, key-value only, up to 25 MiB per value.
• D1: SQLite-based relational SQL, read replicas, great default for app data.
• R2: S3-compatible object storage, no egress fees, ideal for media and backups.
• Durable Objects: one instance per name, strongly consistent, has its own embedded SQLite.
• Hyperdrive: pooling + caching in front of your existing Postgres/MySQL — not a new database.