All jobs

Add an SQLx Offline Query Check to CI

Yes. An agent runs cargo sqlx prepare, commits the query data, and adds a CI job that builds with SQLX_OFFLINE and no database plus a prepare --check step, in a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent starts from why the build needs a database at all. In an Axum API laid out like launchbadge/realworld-axum-sqlx, Cargo.toml takes sqlx 0.5 with runtime-tokio-native-tls, postgres, uuid and time, and Cargo.lock resolves it to 0.5.9. The handlers under src/http/ use the checked macros, 24 calls to query!, query_as! and query_scalar! across users.rs, profiles.rs, articles/mod.rs, articles/comments.rs and articles/listing.rs; each is type-checked at compile time against a live database named by DATABASE_URL, which .env.sample documents and .gitignore keeps out of the repository. src/main.rs embeds migrations/ with sqlx::migrate!() and runs them at startup.

.github/workflows/rust.yml pays for that on every push: a postgres service container, cargo install sqlx-cli --features postgres from source, sqlx db setup, and only then cargo build and cargo test, before the Realworld Postman collection. A contributor without Postgres cannot run cargo check, and rust-analyzer shows an error on every macro. SQLx's answer in the 0.5 line is cargo sqlx prepare, which runs the macros against the database once and writes their checked types to sqlx-data.json; with SQLX_OFFLINE=true the macros read that file instead.

In its sandbox the agent installs sqlx-cli at the 0.5 line to match the crate, starts a Postgres, exports DATABASE_URL and HMAC_KEY as the workflow does, runs sqlx db setup to apply 1_setup.sql through 4_article.sql, and then cargo sqlx prepare, which writes sqlx-data.json at the crate root with one entry per query, keyed by the hash of its SQL. It proves the file is enough with SQLX_OFFLINE=true cargo check after a cargo clean, with no DATABASE_URL in the environment at all, and runs cargo sqlx prepare --check to confirm the file matches the source.

The workflow change is two parts. The existing test job keeps its service and gains cargo sqlx prepare --check after sqlx db setup, so a query edited without re-running prepare fails there with the query it names. A new job with no service runs cargo check with SQLX_OFFLINE: 'true' in its env, which is what a fresh clone experiences. The agent also adds a line to README.md under Setup saying to re-run cargo sqlx prepare after changing a query, and quotes both CI commands' output in the description.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add an SQLx offline query check to this crate's CI. Read Cargo.toml, Cargo.lock, .env.sample, src/main.rs, the query macros under src/http and .github/workflows/rust.yml first. Install sqlx-cli at the same minor version as the sqlx crate, start a Postgres, run sqlx db setup, then cargo sqlx prepare, and commit sqlx-data.json. Prove it works offline with cargo clean and SQLX_OFFLINE=true cargo check with no DATABASE_URL set, and quote the result. In rust.yml add cargo sqlx prepare --check to the existing job after sqlx db setup, and add a second job with no postgres service that runs cargo check with SQLX_OFFLINE set to true. Add one line to the README's Setup section about re-running prepare after a query changes. Open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request with three files: sqlx-data.json, new, with 24 entries; .github/workflows/rust.yml, with the prepare --check step in the test job and a second job that has no services block; and one line in README.md. No Rust source changes, Cargo.toml and Cargo.lock are untouched, and no migration moves.

The description quotes cargo sqlx prepare listing the queries it saved, the offline cargo check finishing with no database variable in the environment, and cargo sqlx prepare --check passing. The run's record keeps the Postgres start, the migrations sqlx db setup applied, and every cargo command, so a reviewer can see the offline build was a clean one.

Before merging, a reviewer confirms the sqlx-cli version the new README line names and decides whether the offline job should also run cargo clippy; the agent keeps it to cargo check, which is the smallest proof that the macros compile without a database.

Run it on every failed Rust workflow

A query that changes without a new sqlx-data.json now fails the prepare --check step on every pull request. An automation with a github trigger on workflow_run.failure starts a run when rust.yml fails, reads the log for the query prepare --check named, starts a Postgres, applies the migrations, re-runs cargo sqlx prepare, and opens a pull request with the refreshed file against the failing branch, with the diff of the entries that changed in its description.

The trigger adds the failed workflow run after the prompt, which says to open nothing when the failure is a test or the Postman collection rather than the query data.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

cargo sqlx prepare is one command, but the proof that the result works is a clean build with no database, which is exactly what a laptop with a running Postgres cannot demonstrate. The agent's sandbox starts with neither and shows the macros compiling from the file alone.

The run keeps every command and its output, including the cargo clean before the offline check, so a reviewer reads a build that could not have used a cached answer. Across a team's SQLx services the same request runs in parallel, one sandbox and one sqlx-data.json each, with each CI change proven against its own queries.

Frequently asked questions

Why sqlx-data.json and not a .sqlx directory?

The crate is on the 0.5 line, where cargo sqlx prepare writes a single sqlx-data.json. The per-query .sqlx/ directory arrived with SQLx 0.7. An upgrade of the crate would move the file; the CI steps stay the same.

Does sqlx-cli have to match the sqlx version?

Yes, on the minor version. The CLI runs the macros' checking code, and a 0.7 CLI writes a format a 0.5 crate does not read. The agent installs it with a --version matching Cargo.lock and says so in the README line.

Does the offline build still need DATABASE_URL at runtime?

Yes. SQLX_OFFLINE only changes what the macros read at compile time. src/main.rs still connects to DATABASE_URL and runs the embedded migrations when the binary starts.

What happens when someone edits a query and forgets prepare?

With SQLX_OFFLINE=true the build fails because the query's hash has no entry in the file, and in the job with a database cargo sqlx prepare --check fails naming it. Either way the pull request shows which query needs a new prepare.

More SQLx jobs

More jobs like this: Hand off a long task

Keep reading