SQLx Offline Query Cache

Windmill uses SQLX_OFFLINE=true in CI, which requires all sqlx::query! / sqlx::query_as! macros to have matching cached query data in backend/.sqlx/.

When to Run

Run after adding or editing a SQL query in Rust source. Without it, CI fails with:

error: `SQLX_OFFLINE=true` but there is no cached data for this query

Do NOT run it when a change only removes queries. The cache is already complete for CI; all that is left are orphaned entries, which are cosmetic and never break a build. Running prepare to tidy them risks destroying the cache for no gain. Delete them offline instead: for each .sqlx/query-*.json, normalize its query field (strip \ line-continuations, collapse whitespace) and check whether it still appears in any .rs file. That detector reports ~48 false positives in a CE checkout, EE queries live in *_ee.rs symlinks it cannot read, so filter to the tables your change touched and delete only those.

Before You Run Anything

1. Back the cache up. prepare deletes .sqlx/ before regenerating, so any compile failure leaves it gutted (observed: 2350 → 142 entries).

   bash .agents/skills/update-sqlx/sqlx-cache.sh backup
   

   Its state is per-worktree, so a sibling worktree running prepare at the same time cannot overwrite your backup.
2. Point DATABASE_URL at THIS worktree's database. prepare compiles every sqlx::query! against the live database. Another worktree's DB lacks your migrations, so every new-table query fails and takes the cache down with it. The symptom is relation "<your_new_table>" does not exist, that is a wrong DATABASE_URL, not a broken query. See AGENTS.md → "Per-worktree ports and database".

Queries Inside Tests Need --all-targets, Which Fails In A CE Checkout