skip to content

For a multi-tenant SaaS on Cloudflare D1, how would you decide between one shared database and one D1 database per tenant?

level: principalimportance: should knowfreq 30%

answer

  1. a hard ceiling per database
  2. one query at a time each
  3. blast radius of a restore
  4. migrations and bindings across thousands

basics

~20 s

D1 is built to scale out across many small databases: each one is capped at 10 GB and runs queries one at a time. Per-tenant databases buy headroom, isolation and per-tenant restores, at the cost of fleet-wide migrations, routing and cross-tenant reporting.

solid answer

~50 s

Start from D1's two per-database ceilings: 10 GB of storage on Workers Paid, which cannot be raised, and a single-threaded engine whose throughput is roughly one over the query duration, returning `D1 DB is overloaded` errors when its queue fills. A shared database is simplest, with one schema, one migration run and cross-tenant SQL, and fits when all tenants together stay well inside those ceilings. One database per tenant spreads load and storage, lets a Time Travel restore rewind one tenant without touching the others, and allows a jurisdiction per tenant. It costs a migration rollout across every database, routing beyond roughly 5,000 bindings per Worker, cross-tenant reports that must fan out, and the account cap: 50,000 databases on Workers Paid by default, raisable on request. A hybrid, with dedicated databases for large or regulated customers and a shared one for the long tail, is also an option.

go deeper

for a junior

Recall D1's 10 GB per-database limit on Workers Paid and that each database runs one query at a time.

for a middle

Explain how query duration sets a database's throughput, what the overloaded errors mean, and which account limits govern how many databases exist.

for a senior

Show how migrations, bindings, restores and residency change when the tenant count reaches thousands, and how replication helps reads but not writes.

for a principal

Own the call: shared, per-tenant or hybrid, the threshold for moving a tenant, and who builds the routing and migration tooling the choice requires.

## The two per-database ceilings D1 documents itself as designed for **horizontal scale-out across many smaller databases**, such as per-user, per-tenant or per-entity databases. Two limits drive that: - **Storage**: a database holds at most **10 GB** on Workers Paid and 500 MB on Free. The 10 GB cap **cannot be raised**. A database past it returns `Exceeded maximum DB size.`, and the documented remedy is deleting rows or sharding into more databases. - **Throughput**: each database is backed by a single Durable Object and is **single-threaded**, processing queries one at a time. At 1 ms per query that is roughly 1,000 queries per second; at 100 ms, roughly 10. Excess requests queue, and a full or slow queue returns `D1 DB is overloaded. Too many requests queued.` or `D1 DB is overloaded. Requests queued for too long.` Read replication raises read capacity, because each replica is its own instance with the same guidelines, but every write still goes to the one primary. ## What a shared database buys - One schema, and **one** `wrangler d1 migrations apply` per release. - Cross-tenant SQL: reports, admin screens and billing queries are a single query. - One binding in the Worker configuration. It fits when all tenants together stay comfortably under 10 GB and the write rate fits one single-threaded primary, with room for the biggest customer to grow. ## What a database per tenant buys - **Headroom**: each tenant gets its own 10 GB and its own query queue, so one noisy tenant cannot overload the others. - **Restore blast radius**: Time Travel overwrites a whole database in place. Per tenant, rewinding one customer's bad import leaves every other customer's data untouched; in a shared database it rewinds everyone. - **Data residency**: a database can be created in a jurisdiction (`eu`, `us` or `fedramp`) with `wrangler d1 create --jurisdiction`, chosen per tenant; it cannot be changed later. - **Offboarding**: deleting a tenant's data is deleting a database. - **Pricing** stays on rows read, rows written and storage; D1 charges nothing per database. ## What it costs 1. **Schema rollout**: every database needs its migrations applied. With thousands of databases that is a tracked, resumable job, and for a while some tenants run the old schema, so Worker code must tolerate both. 2. **Routing**: a Worker script can carry roughly 5,000 D1 bindings, because bindings count against about 1 MB of script metadata. Beyond that the design needs several Workers or another access path; the REST API offers no Sessions API. 3. **Account limits**: 50,000 databases per account on Workers Paid (10 on Free), raisable on request to millions, and 1 TB of total storage per account on Paid, also raisable. 4. **Cross-tenant reporting**: a query runs against one database, so analytics must fan out across databases or be fed from exports. 5. **Operations**: replication settings, restores and exports are per database, so tooling has to loop. ## A comparison | Concern | Shared database | Database per tenant | |---|---|---| | Storage ceiling | 10 GB for everyone | 10 GB each | | Write throughput | one primary for all | one primary each | | Migrations | one run | one run per database | | Time Travel restore | rewinds every tenant | rewinds one tenant | | Residency | one jurisdiction | per tenant | | Cross-tenant SQL | direct | fan-out | ## How a lead decides - Project the largest tenant and the total over two or three years against 10 GB and the write rate one primary can serve. - Ask whether contracts require per-customer restore, deletion or residency; any of those points to per-tenant databases. - Count the tenants: tens fit in bindings easily; tens of thousands need a routing design and an account limit increase first. - Check where reads come from: read replication is enabled per database, so a global read-heavy tenant can get replicas without forcing the setting on everyone. - Consider a hybrid: dedicated databases for the large or regulated customers, a shared database for the long tail, and a lookup that maps a tenant to its database. Whichever way the team goes, write down the threshold that moves a tenant from shared to dedicated, because moving one later means an export, an import and a cut-over.

  • How would you roll out a schema change across 20,000 tenant databases?
    Treat it as a resumable job: loop over the tenant registry, run the migration per database, record each success, and retry failures. Make the change additive first, so Worker code works against both old and new schemas while the fleet is mixed, and remove the old shape only after every database has migrated.
  • When does read replication remove the need to shard by tenant?
    Only when the pressure is reads. Replicas add read capacity and lower read latency, but every write still lands on the single primary, and the 10 GB cap applies to the database whatever its replicas. A write-heavy or fast-growing tenant base still needs more databases.
  • What would make you move a tenant out of a shared database?
    Its share of storage or write load approaching what the shared primary can absorb, a contract asking for its own restore or deletion, or a residency requirement. Moving it means an export of its rows, an import into a new database, and a short cut-over in the tenant-to-database lookup.

  • Ask support to raise the 10 GB limit when one D1 database fills up.
  • Read replication lets one D1 database absorb unlimited write traffic.
  • D1 charges per database, so thousands of databases are expensive.
  • A Time Travel restore of one tenant's table leaves other tenants untouched in a shared database.
  • A single Worker can bind an unlimited number of D1 databases.

Assumes D1's limits as of 2026-10-10: 10 GB per database and 50,000 databases per account on Workers Paid; limits differ by plan and have changed before.