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.