# Storage Selection

> Choose the right Cloudflare storage primitive: D1, R2, KV, Durable Object storage, Hyperdrive, Vectorize, AI Search, cache, or external databases. Use before modeling data, writing migrations, or deciding consistency/cost trade-offs.

- Skill: `zllovesuki/storage-selection` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zllovesuki/storage-selection`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zllovesuki/storage-selection/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: zllovesuki (https://skillmd.com/u/zllovesuki)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zllovesuki/storage-selection

---

# Storage Selection

Use this skill before creating tables, buckets, namespaces, indexes, or object state.

## Storage matrix

| Data shape | Preferred primitive | Why |
|---|---|---|
| Relational records, SQL queries, indexes | D1 | SQLite-style relational storage |
| Large files, media, exports, backups | R2 | Object storage and egress-friendly distribution |
| Globally cached key/value reads | KV | Low-latency cache with eventual consistency |
| Per-entity consistent state and coordination | Durable Object storage | Private storage attached to serialized code |
| Existing Postgres/MySQL | Hyperdrive | Connection acceleration/caching for external DBs |
| Embeddings and vector similarity | Vectorize | Custom vector index/query control |
| Managed retrieval/RAG | AI Search | Ingestion, search, reranking, retrieval features |
| Public static frontend files | Assets/static hosting | Simple and cheap static delivery |

## Decision tree

1. Is the data a large blob or file? Use R2. Store metadata elsewhere.
2. Does the logic require serialized state changes for one entity? Use Durable Objects.
3. Is the data relational and queryable? Use D1, or Hyperdrive if it must remain in an existing Postgres/MySQL database.
4. Is the data a cached, eventually consistent value? Use KV.
5. Is the data an embedding/vector? Use Vectorize, or AI Search if managed retrieval is enough.
6. Is the data public static content? Use assets/static delivery.

## Consistency rules

- Strong coordination belongs in Durable Objects.
- Relational integrity belongs in D1 or the external database behind Hyperdrive.
- Eventual cache belongs in KV.
- Object bytes belong in R2.
- Vector/search data is derived data; maintain a source of truth elsewhere.

## Common composite patterns

### Uploaded document with RAG

```text
R2: original file and parsed chunks
D1: document metadata, owner, ingestion status
Vectorize or AI Search: embeddings/search index
Queue or Workflow: ingestion pipeline
Worker: upload, auth, query API
```

### Collaborative document

```text
Durable Object: live edit coordination and recent state
D1: document metadata and durable history summary
R2: snapshots or exports
Queue: asynchronous compaction/indexing
```

### Multi-tenant SaaS

```text
Worker: auth and routing
D1: tenant/user/application records, possibly per tenant or per group
Durable Object: tenant-level coordination or rate limits
R2: tenant files
KV: public/config cache keyed by tenant
```

## Anti-patterns

- Storing large files in D1 or KV.
- Storing relational data as JSON blobs in R2 without query/index plan.
- Using KV for locks, counters, seat inventory, or balances.
- Using D1 as a single unlimited monolith without a horizontal partition plan.
- Treating Vectorize/AI Search as the only source of truth for documents.