Should Qwik City routeAction$ migrations avoid request-scoped execution?

Direct Answer

No. Database schema migrations should run as a separate deployment step, not inside a routeAction$ handler. Request-scoped execution couples irreversible DDL to HTTP timeouts, client retries, and replica concurrency — risks that deployment-time tooling is designed to avoid.

Why Request-Scoped DDL Is Unsafe

• HTTP semantics mismatch: A 30–60 second timeout or network interruption can leave a migration partially applied. The client may retry, causing duplicate execution unless the migration logic itself is idempotent and lock-coordinated.
• Transaction boundaries are unreliable: Most SQL engines (MySQL <8.0, SQLite, MariaDB) do not support transactional DDL. Even where supported (PostgreSQL, SQL Server, MySQL 8.0+), a failed HTTP response does not guarantee rollback — the transaction may have committed before the response was sent.
• Replica concurrency: Qwik's resume model means concurrent invocations from the same user can hit different replicas. Without sticky sessions or a distributed lock, multiple handlers can attempt the same migration simultaneously.
• Serverless/edge limits: Cloudflare Workers, Vercel Edge, and Netlify Functions impose strict CPU time limits (10–50 ms to 30 s) and may terminate mid-DDL, leaving the schema in an intermediate state with no recovery mechanism.
• Connection pooling breaks transactions: PgBouncer transaction mode, Hyperdrive, Neon, and PlanetScale often disable multi-statement transactions, making transactional DDL impossible.

Feasibility of Idempotent, Lock-Coordinated Migrations in a Handler

Technically possible but strongly discouraged. It requires reimplementing migration tool internals inside an HTTP handler:

1. Acquire a distributed lock (pg_advisory_lock, Redis SETNX, Consul) before DDL.
2. Maintain a migration version table with atomic check-then-apply logic.
3. Write idempotent DDL (IF NOT EXISTS, CREATE OR REPLACE).
4. Handle lock expiration during long-running DDL (e.g., CREATE INDEX CONCURRENTLY).

This adds significant complexity, observability gaps, and operational risk compared to established CLI tools (Flyway, Liquibase, Prisma Migrate, Drizzle Kit).

Migration Status Reporting Should Be Decoupled

A routeAction$ should return application data, not infrastructure state. Use a separate health/readiness endpoint that queries the migration version table, or a dedicated admin action with authentication/authorization separate from user-facing mutations.

Database Engine and Adapter Considerations

No Qwik adapter (Node, Bun, Deno, Cloudflare Workers, Vercel Edge, Netlify Functions) provides built-in transaction safety for DDL. Safety depends entirely on the database engine and driver combination.

Recommended Pattern

1. Run migrations as a distinct, gated CI/CD step before new application replicas receive traffic.
2. Use blue/green or rolling deployments with migration-first ordering.
3. Reserve routeAction$ for application-level mutations that are naturally request-scoped and retry-safe.
4. If self-updating schemas are required (e.g., multi-tenant per-tenant migrations), enqueue a background job (BullMQ, pg-boss, Temporal) from an admin action; a worker executes DDL with proper locking, retries, and observability.

Verification Steps

1. Test your engine's DDL transaction support: BEGIN; CREATE TABLE test (id int); ROLLBACK; — verify the table does not exist.
2. Confirm your ORM/driver + pooler preserves transaction boundaries for DDL. Test a multi-statement migration in a transaction and verify atomic rollback on error.
3. Load-test a slow DDL (e.g., CREATE INDEX CONCURRENTLY) with concurrent requests and client retries. Observe duplicate execution and partial state persistence.
4. Review your deployment pipeline: ensure migrations run as a distinct step before traffic routing. Verify rollback procedure (down migrations, point-in-time recovery, blue/green swap).

One Diagnostic Detail

What database engine, driver, and connection pooler are you using? This determines whether transactional DDL is even possible in your stack and whether a request-scoped approach could be made safe (though still not recommended).