# 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 Rush](https://cloud.getrush.ai/run/add-offline-query-check-to-ci/sqlx/). Opens 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`

```json
{
  "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.

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

- [Add Slow Query Logging to an SQLx + Axum API](https://getrush.ai/run/add-slow-query-logging/sqlx/)
- [Upgrade SQLx From 0.5 to the Current Release in a Rust API](https://getrush.ai/run/upgrade-sqlx/sqlx/)
- [Add Cursor Pagination to a Rust API With SQLx](https://getrush.ai/run/add-cursor-pagination/sqlx/)

## More jobs like this: Hand off a long task

- [Show Online Users in a Socket.IO Chat](https://getrush.ai/run/add-online-users/socket-io/)
- [Add Open Graph Tags to a Leptos App](https://getrush.ai/run/add-open-graph-tags/leptos/)
- [Add Open Graph Tags to an mdBook Site](https://getrush.ai/run/add-open-graph-tags/mdbook/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
