# Update Sqlx

How to safely update SQLx offline query cache.

- Repository: https://github.com/windmill-labs/windmill (18352 stars)
- Category: Data and ML
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add windmill-labs/windmill --skill update-sqlx -g -a claude-code -y`
Codex: `npx skills add windmill-labs/windmill --skill update-sqlx -g -a codex -y`
Cursor: `npx skills add windmill-labs/windmill --skill update-sqlx -g -a cursor -y`
Gemini CLI: `npx skills add windmill-labs/windmill --skill update-sqlx -g -a gemini-cli -y`

## Description

How to safely update SQLx offline query cache. MUST use when SQL queries change.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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
   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

The rest: https://github.com/windmill-labs/windmill/blob/HEAD/.agents/skills/update-sqlx/SKILL.md