All jobs

Set Up SQLx Offline Mode So a Rust App Builds Without a Database

Yes. An agent runs cargo sqlx prepare against a real PostgreSQL, commits the query data, and adds a CI check that keeps it current, in one pull request.

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

What the agent does

SQLx's query! macros check each statement against a live database while the crate compiles, so the agent starts by finding out what a build needs today. In a project like launchbadge/realworld-axum-sqlx, Cargo.toml asks for sqlx = "0.5" with the runtime-tokio-native-tls, postgres, uuid and time features, and Cargo.lock pins 0.5.9. The handlers under src/http/ use query!, query_as! and query_scalar! throughout, and src/main.rs embeds the migrations with sqlx::migrate!(). The workflow in .github/workflows/rust.yml starts a postgres service, runs cargo install sqlx-cli --features postgres with no version and sqlx db setup, and only then cargo build. Without DATABASE_URL, the build fails with DATABASE_URL must be set to use query macros at every call site.

The version matters more than anything else in this job. In the 0.5 and 0.6 lines, offline data is a single sqlx-data.json at the crate root and the macros read it only when the crate's offline feature is on; from 0.7 the CLI writes a .sqlx directory instead, which a 0.5 macro does not look at. So the agent matches the CLI to the lockfile and does not take whatever cargo install resolves: sqlx-cli 0.5.13 with --locked, which still builds on a current stable toolchain. It adds "offline" to the feature list in Cargo.toml. Skipping that step fails quietly: cargo sqlx prepare exits 0, warns no queries found; please ensure that the offline feature is enabled in sqlx, and writes a file that holds only the database name.

Then it generates the data. The sandbox has no Docker, and the README's docker run is only one way to get a server, so the agent installs PostgreSQL from the system packages, sets DATABASE_URL and HMAC_KEY as .env.sample describes, and runs sqlx db setup to create the database and apply the four migrations. A plain cargo sqlx prepare fails here with extra arguments to rustc can only be passed to one target, because the package has both src/lib.rs and src/main.rs. The queries all live in the library, so the command that works is cargo sqlx prepare -- --lib. It writes sqlx-data.json with one entry per distinct query, 23 in this codebase when this page was written, plus the database name.

The agent proves the file does its job by taking the database away. With DATABASE_URL unset, cargo check passes with the file present and fails without it. It then edits one query and confirms both guards trip: cargo sqlx prepare --check -- --lib exits 1 with cargo sqlx prepare needs to be rerun, and a build with SQLX_OFFLINE=true fails on the query that has no saved data. In the workflow it pins the CLI version, adds the --check command to the job that already has PostgreSQL, and adds a second job with no service container that builds with SQLX_OFFLINE=true, so a stale file fails a pull request two ways. The README gains a short section: when to rerun prepare, the -- --lib detail, and that a set DATABASE_URL takes priority over the file unless SQLX_OFFLINE is true.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Set up SQLx offline mode in this Rust project so it compiles without a database. Read Cargo.toml, Cargo.lock (the sqlx version), every use of the sqlx query macros under src/, src/main.rs, migrations/, .env.sample, README.md and .github/workflows/rust.yml first. Match the tooling to the pinned sqlx version: install sqlx-cli from the same minor line with --locked, and enable whatever crate feature that version needs for offline data. There is no Docker here: install PostgreSQL from the system packages, set DATABASE_URL and HMAC_KEY, and run sqlx db setup. Generate the query data with cargo sqlx prepare, passing the target selection it needs for a package with both a library and a binary, and check that the output actually contains the queries. Then prove it: with DATABASE_URL unset, cargo check must pass with the data file and fail without it; after editing one query, cargo sqlx prepare --check must fail and a build with SQLX_OFFLINE=true must fail; revert the edit. In the workflow, pin the sqlx-cli version, add the prepare --check step to the job that has PostgreSQL, and add a job with no database that builds with SQLX_OFFLINE=true. Document in the README when to rerun prepare and how DATABASE_URL and SQLX_OFFLINE interact. Do not upgrade sqlx. Open a pull request with the output of each command.",
  "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

A pull request with one word added to the sqlx features in Cargo.toml, the matching change in Cargo.lock, the new sqlx-data.json, the workflow changes and the README section. The description lists the commands in order with their output from the sandbox: the failed first prepare and the form that works, the build with no database, and the two failures after a query was edited. It names the sqlx-cli version and the Rust toolchain it was built with, and passes on a warning cargo prints during the build, that sqlx-core and sqlx-macros 0.5.9 contain code a future Rust version will reject, as a reason to plan the upgrade separately.

A reviewer opens sqlx-data.json and checks that it has an entry for each query and not just the db key. They check that the CLI pin in the workflow matches the crate's minor version, because a newer CLI would write a format this crate ignores and the check would pass while proving nothing. They decide whether local development should default to offline: the description recommends leaving DATABASE_URL in .env for people who change queries, since they need the live check, and relying on the file for everything else.

Run it on every SQLx repository

This is a job a repository needs once, and the check it adds takes over afterwards. A team with several SQLx services can run it across all of them from a script: send this body to POST /o/{org}/sessions once per repository, each with a request_id that is a UUID v5 of the repository's full name. Running the script again returns the runs already started. Runs past the key's concurrency limit are created queued and start as slots free, so the script needs no retry loop.

If the key has a webhook_url, each run it starts posts run.completed or run.failed there when it ends, with the session URL to read the pull request from.

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

Why run it on Rush?

Offline mode can only be set up online. Generating the data needs a PostgreSQL with the schema applied, the right CLI built from source, and a full compile, and then the result should be tested by removing the database again. That is tedious on a laptop that already has a different sqlx-cli installed globally. The agent does it in a sandbox made for the run, where the CLI version is whatever the lockfile calls for and nothing else is installed, and the run keeps every command and its output.

The failures along the way are the useful part of the record. The prepare that exits 0 with an empty file, the one that refuses a package with two targets, the stale-data errors: each is in the run's transcript with the fix that followed. A reviewer sees that the committed file was produced by the path that works and can copy the exact commands into the README of the next service.

Frequently asked questions

Why is my sqlx-data.json almost empty?

On the 0.5 and 0.6 lines the macros only record query data when the offline feature of the sqlx crate is enabled. Without it cargo sqlx prepare still succeeds and writes a file with just the database name, along with a warning that is easy to miss. Add the feature and run it again.

Why does cargo sqlx prepare fail with an error about rustc targets?

The command passes extra arguments to rustc, which cargo allows for one target at a time, and a package with both a library and a binary has two. Pass the choice after --, for example cargo sqlx prepare -- --lib when the queries are in the library. The same flag goes on the --check form in CI.

Does this also remove the database from the test job?

No. Offline mode covers compilation only. This application runs its migrations at startup and the workflow's API test step talks to a real server, so that job keeps its PostgreSQL service. What changes is that a plain build no longer needs one.

More SQLx jobs

More jobs like this: Hand off a long task

Keep reading