SQLx Documentation

What SQLx is

SQLx is an async SQL crate for Rust that supports PostgreSQL, MySQL and SQLite. It is not an ORM: you write plain SQL. Its best-known feature is the query! and query_as! macros, which check each query against a real database while your code compiles, so a misspelt column or a wrong Rust type fails the build instead of a request. It also provides connection pools such as PgPool, transactions, and migrations through the sqlx-cli tool and the migrate! macro.

Where to read

The API documentation on docs.rs is the main reference, with the README and the examples folder in the GitHub repository filling in the details. The sqlx-cli README explains migrations and offline mode. The project moved to the transact-rs GitHub organisation with the 0.9 release, and the 0.9 changelog is worth reading if you follow older tutorials, since query() now only accepts static strings unless you wrap a built string in AssertSqlSafe.

Is it worth learning?

For a Rust backend on PostgreSQL, it is the most common choice, and it keeps your SQL visible, which suits anyone who learnt SQL properly first. If you would rather build queries in Rust code, Diesel is the main alternative.

The parts that matter most

• Pools: create one PgPool with PgPoolOptions at startup, set max_connections, and share it through your Axum state.
• Query macros: query_as! maps rows onto your structs and needs DATABASE_URL set when you build.
• Offline mode: cargo sqlx prepare saves query metadata to a .sqlx folder; commit it so CI can compile without a database.
• Migrations: sqlx migrate add, sqlx migrate run, and -r for reversible up and down files.
• Testing: #[sqlx::test] creates a fresh database for each test and applies your migrations automatically.

Prerequisites

SQL and PostgreSQL basics, Rust with Result and ?, and async/await on Tokio.

Free or paid?

Free and open source.

What you can do after it

Run type-checked SQL from an Axum API, manage schema changes with migrations, use transactions correctly and test against a real database in CI.

Common questions

Why does my project not compile without a database? The macros need either DATABASE_URL or the prepared .sqlx folder.

Can I build dynamic queries? Yes, with QueryBuilder, which keeps values as bound parameters.