| name | storage-selection |
| description | 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.
|
| compatibility | Cloudflare Workers TypeScript projects using Wrangler; verify current Cloudflare APIs, limits, and pricing before production use. |
| metadata | {"source":"Architecting on Cloudflare plus official Cloudflare Developer Platform docs","generated":"2026-04-28"} |
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
- Is the data a large blob or file? Use R2. Store metadata elsewhere.
- Does the logic require serialized state changes for one entity? Use Durable Objects.
- Is the data relational and queryable? Use D1, or Hyperdrive if it must remain in an existing Postgres/MySQL database.
- Is the data a cached, eventually consistent value? Use KV.
- Is the data an embedding/vector? Use Vectorize, or AI Search if managed retrieval is enough.
- 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
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
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
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.
