Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/launchbadge/sqlx/llms.txt

Use this file to discover all available pages before exploring further.

The query!, query_as!, and related macros verify your SQL at compile time by connecting to a real database. This works well on a developer machine, but CI servers and documentation build environments typically do not have a live database available. Offline mode solves this by caching the metadata that the macros need into a .sqlx directory that you check into version control.

​
How offline mode works

When you run cargo sqlx prepare, it compiles your project with a live database connection, captures the query metadata returned by the database for each query! invocation, and writes that metadata to .sqlx/. On subsequent builds where SQLX_OFFLINE=true is set (or where no DATABASE_URL is present), the macros read from .sqlx/ instead of talking to a database.

​
Generating the .sqlx cache

Run cargo sqlx prepare from your project root with DATABASE_URL set: 
cargo sqlx prepare
This writes per-query JSON files into .sqlx/: 
.sqlx/
├── query-3a7f2b...json
├── query-8c91de...json
└── query-f04a12...json
cargo sqlx prepare must be run as cargo sqlx, not as a standalone sqlx binary, because it needs access to Cargo’s build environment to find all query macro invocations.

​
Workspace projects

For workspaces where multiple crates use query macros, pass --workspace to generate a single .sqlx directory at the workspace root rather than one per crate: 
cargo sqlx prepare --workspace
Check this single .sqlx directory into version control. All crates in the workspace will read from it during offline builds.

​
Checking .sqlx into version control

Add the .sqlx directory to your repository so that CI can build without a database: 
git add .sqlx
git commit -m "Update sqlx query cache"
Once .sqlx is committed, any machine that clones the repository can build the project with SQLX_OFFLINE=true.

​
Building in offline mode

Set SQLX_OFFLINE=true to tell SQLx to read from .sqlx instead of connecting to a database: 
SQLX_OFFLINE=true cargo build
If both DATABASE_URL and .sqlx are present, DATABASE_URL takes precedence unless SQLX_OFFLINE=true is explicitly set. Add SQLX_OFFLINE=true to your .env file to make offline the default for local builds: 
# .env
SQLX_OFFLINE=true
DATABASE_URL=postgres://localhost/mydb  # still used by cargo sqlx prepare
cargo sqlx prepare always connects to the database regardless of SQLX_OFFLINE, so this combination is safe.

​
Validating the cache in CI

Use cargo sqlx prepare --check to verify that .sqlx is up to date with the current database schema and queries. It exits with a non-zero status if anything is out of sync, making it suitable as a CI gate: 
cargo sqlx prepare --check
# OR for workspaces:
cargo sqlx prepare --check --workspace
Add this to your CI pipeline to catch cases where a developer added or changed a query without regenerating the cache.

​
Git pre-commit hook

To keep .sqlx automatically up to date, install a pre-commit hook that runs cargo sqlx prepare before each commit: 
echo "cargo sqlx prepare > /dev/null 2>&1; git add .sqlx > /dev/null" > .git/hooks/pre-commit
This hook does not block the commit if cargo sqlx prepare fails — it is an ergonomic choice to avoid blocking work in progress. Use cargo sqlx prepare --check in CI as the authoritative gate.

​
Building on docs.rs

docs.rs does not have access to your database and does not set SQLX_OFFLINE. You can detect the docs.rs environment via the DOCS_RS environment variable and force offline mode from a build.rs script.
1

Generate the .sqlx cache

Run cargo sqlx prepare locally and commit the .sqlx directory to your repository.
2

Create build.rs

Add a build.rs file at the same level as your Cargo.toml:
fn main() {
    // When building on docs.rs, enable offline mode so the query! macros
    // read from .sqlx instead of trying to connect to a database.
    if std::env::var_os("DOCS_RS").is_some() {
        println!("cargo:rustc-env=SQLX_OFFLINE=true");
    }
}
3

Verify the build

Push to docs.rs or simulate the environment locally:
DOCS_RS=1 cargo build

​
Including feature-flagged queries

By default, cargo sqlx prepare only processes queries reachable under the default feature set and the default compilation targets. To include queries that are behind feature flags or inside #[cfg(test)] blocks, pass additional arguments to Cargo after --: 
# Include all targets (tests, examples, benchmarks) and all features
cargo sqlx prepare -- --all-targets --all-features
This is especially important if you have queries inside integration tests or behind optional features, as those queries will not be included in .sqlx without this flag.
If you use cargo sqlx prepare --workspace, combine it with --all-targets --all-features to ensure every query across the entire workspace is captured:
cargo sqlx prepare --workspace -- --all-targets --all-features

Build docs developers (and LLMs) love

Get started for freeTalk to us