SKILL.md
Overview
SQLx is an async, pure Rust SQL crate featuring compile-time checked queries without a DSL. It supports PostgreSQL, MySQL, MariaDB, and SQLite. It is not an ORM but a toolkit for running raw SQL queries safely and efficiently.
Capabilities
- Compile-time verification: Checks queries against a live database at compile time using macros (
query!,query_as!). - Async/Await: Built from the ground up for async execution (tokio, async-std, actix).
- Database Agnostic: Supports multiple databases with a consistent API.
- Pure Rust: Drivers are written in pure Rust (except SQLite which links to C library).
- Connection Pooling: Built-in pooling with
Pool.
Usage
Installation
Add sqlx to Cargo.toml with the necessary features (runtime + database).
# Example: Tokio + Postgres
[dependencies]
sqlx = { version = "0.8", features = [ "runtime-tokio", "tls-native-tls", "postgres" ] }Connection
Create a connection pool (recommended) or a single connection.
use sqlx::postgres::PgPoolOptions;
let pool = PgPoolOptions::new()
.max_connections(5)
.connect("postgres://user:pass@localhost/db").await?;Querying
Use sqlx::query (unprepared/prepared) or sqlx::query! (compile-time checked).
Runtime Query (Dynamic)
let row: (i64,) = sqlx::query_as("SELECT id FROM users WHERE email = $1")
.bind("[email protected]")
.fetch_one(&pool).await?;Compile-time Checked Query (Macros)
Requires DATABASE_URL environment variable or .env file.
let countries = sqlx::query!(
"SELECT country, count FROM countries WHERE organization = ?",
organization
)
.fetch_all(&pool).await?;Migrations
Add migrations with sqlx migrate add -r <description> (use underscores instead of spaces in description). After adding, update the SQL code in migrations/<timestamp><description>.up.sql and migrations/<timestamp><description>.down.sql. Run migrations with sqlx migrate run. See sqlx --help and sqlx migrate --help for more options.
sqlx::migrate!("./migrations").run(&pool).await?;References
- Documentation: docs.rs/sqlx (Primary API reference)
- Repository: github.com/launchbadge/sqlx (Examples, FAQ)
- Examples: See the
examples/directory in the repository for patterns.