Architecture notes · build-in-public

Choosing D1 over Postgres for an all-Cloudflare build

The decision, as written down

The architecture table in the design doc names the relational store and its reason in one line: relational data is D1 (SQLite), "all-Cloudflare for the slice; swap to Supabase Postgres later if needed." The same doc's decisions section lists "D1 for the slice" under Locked, and lists "D1 vs Supabase Postgres at scale (revisit if/when multi-user)" under Open. So the choice and its expiry condition were both recorded up front.

This matters because the project's governing principle is to resist over-engineering — the senior trap the course's own Track 0 teaches. Standing up a managed Postgres, a connection pooler, and the networking to reach it from an edge Worker is real work. For a build whose first job is to ship a thin vertical slice end-to-end, the question isn't "which database is best in general" but "what lets the loop ship while keeping the swap cheap." D1 answered that.

Why D1 fit the slice

• It's native to the stack. The whole architecture is Cloudflare-native — Workers, R2, Durable Objects, AI Gateway. D1 is the relational piece of that same platform, bound to the Worker as DB in wrangler.jsonc with no external network hop, no pooler, and no second vendor to provision.
• It runs locally with no cloud. The first two slices were designed to need no cloud account at all — wrangler dev uses a local D1 by default, ignoring the pinned production database id. That kept the inner loop fast and free.
• The data model is modest. D1 holds content metadata and learning state — users, lessons, objectives, items, attempts, reviews, mastery. The lesson bodies were always intended to live in R2 as MDX, not in the relational store. SQLite is a comfortable fit for that shape.
• It stayed on the free tier. D1 (and the SQLite-backed coach Durable Object) run on Cloudflare's free plan; only Vectorize / AI Search forced the paid plan later. The database choice didn't gate shipping.

The boundary that makes it reversible

A decision marked "swap later if needed" is only honest if the swap is actually cheap. The project's standing rule is to isolate churny or swappable services behind a thin src/lib/ layer so a change is a one-file fix. Database access follows the same instinct: routes don't hand-write SQL against D1 everywhere — they go through helpers in src/lib/db.ts, and grading specifically runs through one shared function in src/lib/grade.ts that does the full attempt-plus-review-plus-mastery write. Concentrating the persistence calls is what keeps "move to Postgres" a contained edit rather than a scavenger hunt.

The honest caveats

This is not a claim that D1 beats Postgres. It's a claim that, for an education-first vertical slice on an all-Cloudflare stack, D1 was the lower-friction choice and the design doc says so. The open question is real: the doc itself flags the at-scale comparison as unresolved, and names Supabase Postgres as the concrete alternative if multi-user load arrives. The skill on display isn't picking SQLite — it's recording the decision, its reason, and the condition that reverses it, then building the boundary that keeps the reversal cheap.