update-sqlx

Regenerates the SQLx offline query cache safely after Rust SQL query changes.

17.8k|1.1k|Updated May 5, 2022
One-click install
npx skills add https://github.com/windmill-labs/windmill --skill update-sqlx
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: update-sqlx
Source: https://github.com/windmill-labs/windmill/tree/main/.agents/skills/update-sqlx
Command: npx skills add https://github.com/windmill-labs/windmill --skill update-sqlx

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) components.

What problem does it solve?

Windmill's CI runs with SQLX_OFFLINE=true, so every sqlx::query! macro needs matching cached data in backend/.sqlx/. Running cargo sqlx prepare naively deletes the entire cache before regenerating it, which silently destroys enterprise-edition query entries and breaks CI whenever compilation fails partway.

Core Features & Use Cases

  • Safe cache regeneration: Restores the full cache from origin/main, regenerates OSS entries, then grafts back any EE entries that prepare deleted.
  • Backup and restore workflow: The bundled sqlx-cache.sh script snapshots backend/.sqlx, lists newly added queries, and restores the backup with only verified new entries grafted on.
  • Test-target query handling: Documents how to cache queries inside tests/*.rs using --all-targets despite the known CE-checkout abort, and how to verify both lib and test targets afterward.
  • Use Case: After adding a new SQL query to a Rust source file, run the documented procedure to update the offline cache without wiping the 2000+ existing EE entries, then confirm with git diff origin/main --stat backend/.sqlx/.

Quick Start

Update the SQLx offline cache for my new query by backing up backend/.sqlx with the sqlx-cache script, running cargo sqlx prepare against this worktree's database, and restoring any deleted EE entries.

Frequently Asked Questions about update-sqlx

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I update the SQLx offline cache after changing a query?▼

Back up backend/.sqlx first, then run cargo sqlx prepare --workspace with the all_sqlx_features flag against a live database. Afterward restore any EE cache entries deleted by prepare and verify with git diff against origin/main.

Why does CI fail with 'no cached data for this query' in SQLx?▼

CI runs with SQLX_OFFLINE=true, so every sqlx::query! macro needs a matching entry in backend/.sqlx/. The error means you added or edited a query without regenerating the cache, or a test-target query was never compiled during prepare.

Why does cargo sqlx prepare delete existing cache files?▼

prepare empties backend/.sqlx before regenerating and only writes entries for code it actually compiles. Without the private EE feature or with a failed compilation, it silently deletes enterprise query caches, so always back up first and restore missing entries from origin/main.

How do I cache SQLx queries inside Rust test files?▼

Run cargo sqlx prepare with --all-targets so test targets compile and their queries get cached. In a CE checkout this aborts partway due to an EE-only import, so back up first, then graft only the new entries onto the restored backup.

Should I run cargo sqlx prepare when I only removed queries?▼

No. A removal-only change leaves orphaned cache entries that are cosmetic and never break CI. Instead, manually delete the specific .sqlx/query-*.json files whose normalized query text no longer appears in any .rs file, filtered to the tables your change touched.

Why does prepare fail with 'relation does not exist' errors?▼

That error means DATABASE_URL points at the wrong database, typically another worktree's database that lacks your migrations. Point DATABASE_URL at this worktree's own database so prepare compiles queries against the correct schema.