Running Cloudflare D1?

Cloudflare D1 queries slow or stale on the edge? We sort it out.

D1 is clever and has sharp edges: a read from a replica can return data from before your last write, a 10 GB database limit sneaks up during an import, and a Worker that batched inserts yesterday hits a row count error today. We work the queries, the schema and the Worker bindings together until it is one coherent system rather than three.

  • Since 2015Fixing technology
  • FreeEstimates
  • US teamReal engineers

wrangler-d1.log

still broken

What it is

Cloudflare D1 at a glance

Cloudflare D1 is a serverless SQLite database that lives inside the Cloudflare developer platform. It was first announced in 2022 and moved to general availability in April 2024, with read replicas and larger database limits still carrying alpha or beta labels in parts of the product.

D1 is accessed from Workers through a binding, and queries go to a primary region with optional replication to other regions for reads. Because the engine is SQLite, the SQL surface is small and the per query cost is tiny, but the operational model is quite different from a long lived Postgres cluster, and the limits on database size, statement length and parameter count will bite applications that do not design for them.

Type
Serverless SQLite database on the Cloudflare edge
First released
2022 announced, 2024 general availability
License
Proprietary managed service, usage based pricing
Maintained by
Cloudflare, Inc.
Typically used for
Workers backends, edge metadata stores, session or profile data, lightweight SaaS schemas

The honest version

Cloudflare D1 pros and cons

No technology is all upside. This is where Cloudflare D1 earns its place and where it tends to cause trouble.

Where Cloudflare D1 is strong

  • Native to the Workers runtimeA D1 binding is a one line config, and the query API is a Promise based client that fits naturally inside a Worker handler, with no connection pool to manage.
  • Serverless pricing at low volume is cheapYou pay for rows read, rows written and storage, and small projects stay inside the free tier comfortably, which is unusual for a managed relational database.
  • SQLite is a known, boring engineThe query planner, SQL dialect and reliability story are decades proven, so you inherit a quiet foundation rather than a rewritten one.
  • Read replicas are built inReplication across regions is enabled by a config flag, not a separate cluster, so adding edge read capacity is a short exercise rather than a project.
  • Migrations have first class toolingwrangler d1 migrations create and apply handle schema versioning, and the files sit alongside the Worker code in git.
  • Low latency from WorkersBecause the binding runs inside the same runtime as your code, a round trip to the primary region often clocks under 20 ms from the Worker, not from the user.

Where Cloudflare D1 bites

  • Read replicas can return stale dataReplication is asynchronous, so a read right after a write may return the old row for up to a second or two. Any workflow that writes and then reads has to plan for it explicitly.
  • Database size limits are realAlpha and beta versions of the product capped databases at 10 GB, with per row and per statement limits on top. Even once lifted, D1 is not the place for a 500 GB warehouse.
  • The SQL surface is SQLite, not PostgresNo arrays, no JSONB operators, limited window function coverage in older versions, and no stored procedures. Teams moving from Postgres have to rewrite more queries than they expect.
  • Vendor lock in to CloudflareD1 is only accessible through Workers and the HTTP API. Moving to a self hosted SQLite or another provider means exporting, transforming and reimporting rather than a drop in swap.
  • Error messages are terseA D1_ERROR with a short string often sits on top of a SQLite error without the full context, so debugging means attaching your own logging or digging through wrangler tail.
  • Worker CPU limits complicate migrationsLong running migrations or bulk operations have to be chunked to fit the Worker CPU budget, which turns a one liner in Postgres into a pipeline here.

Sound familiar?

Common Cloudflare D1 problems we fix

The Cloudflare D1 problems that bring people to us, and what you have once each one is fixed.

D1_ERROR: database or disk is full

The database has hit its size cap

A dataset that crossed the alpha size limit during an import, often from uncompressed text columns, a missing archival job, or a logs table that should have been in R2 instead.

Storage within the plan, growth controlled

D1 read replica lag

Reads are returning stale data

A write to the primary region that has not yet propagated to the replica serving the read, usually visible as a user who sees their own update missing on the next page.

Reads respect recent writes

D1_ERROR: too many SQL variables

A batch insert is being rejected

A prepared statement with more than the parameter cap, usually from building a single INSERT with hundreds of placeholders instead of batching rows into groups.

Batches within the parameter limit

wrangler d1 migrations applied out of order

Migrations are landing in the wrong order

Two engineers who added migrations on separate branches, so the filenames sort one way locally and another way in production.

Migrations linear and tracked

Worker exceeded CPU time

A migration or batch job runs out of CPU budget

A single Worker call trying to process too many rows, hitting the CPU limit before it finishes, and leaving the schema in a half migrated state.

Jobs chunked to fit the budget

D1_ERROR: database is locked

Writes are being blocked by concurrent operations

Multiple writers hitting the same database at once, often from a scheduled Worker overlapping with user traffic on a hot table.

Writes serialized sensibly

Error 7500 from D1 API

The D1 API itself returns an opaque error

A Cloudflare side incident, a region outage, or a request shape the API is briefly refusing. Retry logic and a working status page link make this survivable.

Retries handle transient faults

no such column after migration

A query references a column that is not there yet

A deploy where the Worker binary shipped before the migration applied, so the first few requests crash until the schema catches up.

Schema leads code reliably

What we do

Cloudflare D1 help, from schema to replicas

Call us for one failing query, or hand over the whole Worker and D1 setup for a review.

Rescue
A D1 database that is full, locked or rejecting writes. We take the pressure off first and dig into the cause after.
Schema and migrations
A migration pipeline that stays linear across branches, with rollback plans and dev to prod parity you can actually trust.
Query and index tuning
EXPLAIN output, index design and pagination patterns worked out so Workers stay inside their CPU budget.
Replica strategy
Read replica setup, consistency expectations, and the code patterns that avoid stale reads on the paths that cannot tolerate them.
Migrations off D1
When D1 has stopped being the right answer, we move you to Turso, Postgres or self hosted SQLite without downtime.
Managed Tech
Backup verification, size tracking against plan limits, and a Workers engineer on call when the dashboard tells you less than you need.

How it works

From first message to fixed

  1. Look Free estimate

    Tell us what's going wrong. We look at it, then tell you plainly what's wrong and what it will cost.

  2. Fix

    We fix the cause, not the symptom. If something is down, getting it back up comes first.

  3. Harden

    Backups, monitoring, updates and access, so the same problem can't quietly come back.

  4. Hand back or stay on

    You get a plain-language write-up. Or we stay on for hosting, upkeep and new work.

Often found together

Running Cloudflare D1 alongside something else?

We work on the whole stack, so the problem can be wherever it actually is.

Questions

Cloudflare D1 questions

Something else? Call+1 737 727 7327

Why does my Cloudflare D1 read return stale data?

Read replicas update asynchronously from the primary region, so a read that follows a recent write can return the row's previous value for a short window. For paths that have to be read your own writes, the two usual answers are to route that specific query to the primary region, or to cache the just written value in the Worker until the replica catches up. Which one fits depends on how much latency you want to trade.

What are the D1 size and parameter limits?

At the time of writing the per database size cap sits at 10 GB in the generally available tier, with larger databases available in beta. There is also a cap on SQL variables per statement, usually a few hundred, and a statement length limit. Bulk operations have to be chunked to respect both.

Can we use D1 like Postgres?

Partly. The engine is SQLite, so you get standard SQL and a subset of JSON functions, but no arrays, no JSONB operators, no stored procedures and a smaller window function set than Postgres. Most Postgres schemas port, but some queries and types do not and have to be rewritten.

How do we handle long migrations that exceed the Worker CPU limit?

Break the migration into steps that each fit the CPU budget, and run them from a queue or scheduled Worker rather than a single call. Alembic style data migrations that touch every row need to batch by primary key and resume from a cursor; the schema change itself is usually fine in one shot.

When should we move off D1 to Turso or Postgres?

When your dataset approaches the D1 size cap, when you need Postgres only features like LISTEN NOTIFY or JSONB indexes, or when the application no longer runs mostly on Workers. We will tell you plainly when staying with D1 is still the right trade and when it is not.

How much does Cloudflare D1 help cost?

The estimate is free. Send us the failing query or a quick summary of the setup, and a price lands before any engineering begins.

Free estimate

D1 misbehaving?

Share the wrangler output or a sketch of the schema, and a Workers engineer replies with a plan and a price.

  • No charge to find out what it will take
  • If it's urgent, say so

Replies come from a person. By sending, you authorize us to email you back. No marketing.