vibed/quotesdb/.beans/quotesdb-zlfi--triage-database-migration-strategy-for-cloudflare.md

title	status	type	priority	created_at	updated_at
[TRIAGE] Database migration strategy for Cloudflare Workers (startup vs wrangler d1 execute)	completed	task	critical	2026-03-10T23:32:07Z	2026-03-10T23:32:07Z

This is a triage decision ticket. It must be resolved before dependent implementation tickets can proceed. Database migration strategy for Cloudflare Workers: how should the `quotes` and `quote_tags` tables be created? Workers do not have a persistent startup phase like a long-running server. 1. **Startup migration** — run `CREATE TABLE IF NOT EXISTS` in the Worker fetch handler before processing the first request. Simple but adds latency to the first request. 2. **`wrangler d1 execute`** — apply the schema separately using the wrangler CLI. No runtime overhead but requires a separate CI step. 3. **SQLx migrate! macro** — embed migrations in the binary and run them at startup. Depends on SQLx compatibility with workers-rs (see TRIAGE e8a330). **Option 2: `wrangler d1 execute` as a separate CI/CD step.**

• Option 3 (SQLx) is ruled out — TRIAGE e8a330 established that SQLx is incompatible with workers-rs/D1.
• Option 1 (startup migration from the Workers handler) is impractical: Workers spin up per-request via V8 isolates. Running DDL before every request adds latency and is fragile.
• Option 2 is the canonical Cloudflare-recommended approach. It is idempotent (CREATE TABLE IF NOT EXISTS), keeps the Workers handler free of DDL overhead, and integrates cleanly into CI/CD as a post-tofu apply step.

Production: wrangler d1 execute quotesdb --file infra/schema.sql --remote — run once after first tofu apply, and again for each incremental migration file.

Local dev / tests: NativeRepository::run_migrations() (ticket 00aff0) runs execute_batch via rusqlite on native startup. No manual wrangler step needed.

This decision is co-resolved with TRIAGE 5c0c64, which asked the same question from the OpenTofu angle. Both arrive at the same answer.

- Co-resolved with TRIAGE 5c0c64. - Ticket a5049d updated with chosen strategy. - Ticket bb1514 created: implementation plan for `infra/schema.sql`. - Ticket 75489a updated: documents the wrangler workflow. `chore(quotesdb): resolve triage — database-migration-strategy-for-cloudflare-workers-startup-v`