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

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

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

- [Add an SQLx Offline Query Check to CI](https://getrush.ai/run/add-offline-query-check-to-ci/sqlx/)
- [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/)

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