bsql

Compile-time-safe SQL for Rust — PostgreSQL and SQLite, async and sync.

Write real SQL. It is checked at cargo build against the schema your migration files define — table names, column names, types, nullability. If it compiles, the query is correct. No DSL, no method chains, no runtime "column not found".

1.0.0-alpha.5 — stable in shape, early in life; expect a few more alpha iterations before a full 1.0.

// migrations/0001_init.sql →  CREATE TABLE users (id int PRIMARY KEY, email text NOT NULL);

// Typed at build time against the migration above.
// `SELECT nope FROM users` would be a compile error, not a runtime surprise.
bsql::query!(UserById, "SELECT id, email FROM users WHERE id = $1");

let user = conn.query_one::<UserById>((42_i32,)).await?;
// user.id: i32   user.email: String     (a nullable column would be Option<T>)

• If it compiles, the SQL is correct. Every query is validated at build time against the schema your migration *.sql files describe — names, types, and nullability. Wrong column, wrong type, typo → the build fails.
• One query function, and it always checks — no accidental unchecked path. In sqlx a missing ! (query() vs query!()) silently skips validation. bsql has a raw-SQL escape hatch too, but it is deliberate and named apart: the unchecked verbs carry a distinct suffix (query_raw for raw text, query_params for raw text plus runtime parameters), so you opt into unchecked SQL on purpose — never by forgetting a !.
• Pure SQL text — no builder. CTEs, JOINs, window functions, subqueries — no .filter().eq() method chains to learn. If PostgreSQL or SQLite supports it, you just write it.
• Async and sync are both first-class. Both drivers plug the same socket into ONE transport-generic core, so parity is a compiler guarantee, not hand-maintained twins. The sync driver drops tokio entirely — pure fn, no async runtime. Switch async↔sync by swapping one feature line (and dropping .await).
• PostgreSQL and SQLite, same macro. The same query! carrier runs on both for typed reads, decoding into the same records — and SQLite verifies each value's storage class at runtime (a mismatch is a classified error, never a silent coercion). Typed writes through query! (execute / execute_batch / query_batch) are a PostgreSQL capability; on SQLite the typed flagship is read-only, and dynamic writes (execute_raw / execute_params) work on both.
• Tiny footprint. ~1.7–1.8 MB peak memory for a real PostgreSQL workload — the leanest client measured there (and a near-tie with raw C on SQLite), ~8× under a C/libpq client, ~10× under Go/pgx, and ~3.6× under the nearest Rust client — and the whole TLS/SCRAM stack is feature-gated, so a localhost / trust-auth build is a handful of crates.
• #![forbid(unsafe_code)] on every shipped crate. No unwrap/expect in production code. NULL is Option<NonZeroU32>, not a sentinel. The hot decode path is proven panic-free and byte-stable by a machine-checked codegen gate.
• Things nobody else does — automatic N+1 detection, a build-time destructive-migration gate, Rust types generated from your migrations, typed binary COPY, and sub-millisecond schema-per-test isolation. See What makes it different.

Explore the Full Cross-Language Benchmark Suite & Methodology 🫢 Seven clients across four languages (bsql, C/libpq, C/sqlite3, Go/pgx, Go/mattn, tokio-postgres, sqlx, diesel).

Point read latency (SELECT by-PK, 1 connection, lower is better):

bsql (sync)      [████                    ] 24.6 µs   (1.0x)  1.69 MB
bsql (async)     [████▌                   ] 26.2 µs   (1.1x)  1.80 MB
C / libpq        [████                    ] 25.5 µs   (1.0x) 13.25 MB
sqlx             [████▌                   ] 27.9 µs   (1.1x)  6.73 MB
tokio-postgres   [██████▌                 ] 39.8 µs   (1.6x)  6.50 MB
diesel           [███████                 ] 41.3 µs   (1.7x)  7.01 MB
Go / pgx         [█████████               ] 52.1 µs   (2.1x) 16.81 MB

Point read latency (SELECT by-PK prepared, lower is better):

C / sqlite3      [██                      ] 1.51 µs  (1.0x)   3.83 MB
bsql             [██                      ] 1.58 µs  (1.0x)   3.86 MB
diesel           [██▌                     ] 1.87 µs  (1.2x)   4.08 MB
Go / mattn       [████                    ] 3.25 µs  (2.2x)  16.94 MB
sqlx             [████████                ] 6.16 µs  (4.1x)   4.59 MB

• On 10–100 row queries and batch inserts (751 µs vs 909 µs), bsql is 15–20% faster than raw C.
• On 10,000 rows, bsql (1.02 ms) is 14× faster than sqlx (14.19 ms), which hops threads on every row.
• Peak RSS is a virtual tie with raw C (3.86 MB vs 3.83 MB).

# Cargo.toml  (alpha is a pre-release, so pin the exact version)
[dependencies]
bsql = { version = "1.0.0-alpha.5", features = ["macros", "postgres-async"] }

[build-dependencies]
bsql-build = "1.0.0-alpha.5"

// build.rs — replays migrations/ into the schema catalog query! reads.
fn main() -> Result<(), bsql_build::BuildError> {
    bsql_build::emit("migrations")
}

use bsql::pg;

bsql::query!(UserById, "SELECT id, email FROM users WHERE id = $1");

#[tokio::main]
async fn main() -> Result<(), bsql::pg::DriverError> {
    let cfg = pg::ConnectConfig::from_dsn("postgres://user@localhost/mydb")?;
    let mut conn = pg::Connection::connect(cfg).await?;

    let user = conn.query_one::<UserById>((42_i32,)).await?;
    println!("{} <{}>", user.id, user.email);
    Ok(())
}

Runnable examples. The examples/ directory is a heavily-commented tour that doubles as a usage guide — one focused program per feature (basic CRUD, cross-backend, params vs raw, joins/aggregates, migrations, generated types, external-type bridges, N+1 detection, typed COPY, pipelining/batch, streaming, transactions, pooling, schema-per-test). The SQLite ones run with zero setup: cargo run -p bsql-examples --bin basic_sqlite.

let authors = conn.query::<AllAuthors>(()).await?;
for a in authors.iter() {
    // one query per author, from the same source line — the anti-pattern
    let books = conn.query::<BooksByAuthor>((a.id,)).await?;
}

if let Some(n1) = conn.n1_report() {
    // N1Report { sql: "SELECT … FROM books WHERE author_id = $1",
    //            file: "src/catalog.rs", line: 42, count: 250 }
    eprintln!("N+1 at {}:{} ran {}×", n1.file, n1.line, n1.count);
}

-- migrations/0007_drop_legacy.sql
-- bsql:ack-destructive
DROP TABLE legacy_sessions;   -- compiles ONLY because of the ack line above

-- migrations/0003_types.sql
CREATE TYPE mood AS ENUM ('happy', 'sad');

bsql::user_types!();   // generates:  pub enum Mood { Happy, Sad }

bsql::query!(GetMood, "SELECT mood FROM users WHERE id = $1");
let m: Mood = conn.query_one::<GetMood>((1_i32,)).await?.mood;

copy!(LoadUsers, "users", (id, email));    // validated against the catalog

conn.copy_in_typed::<LoadUsers>(
    people.iter().map(|p| (p.id, p.email.as_str()))    // one typed tuple per row
).await?;

#[bsql::test]
async fn creates_a_user(conn: &mut bsql::pg::Connection) {
    conn.query_raw("CREATE TABLE users (id int)").await.unwrap();  // in an ISOLATED schema
}   // schema auto-dropped, even if the test panics

let report = conn.run_migrations(
    bsql::MigrationSource::directory("migrations")
).await?;
// report.applied — the migrations newly applied this run, in order

let pool = pg::Pool::builder(cfg, 16)
    .max_lifetime(Some(Duration::from_secs(1800)))
    .idle_timeout(Some(Duration::from_secs(300)))
    .slow_query_threshold(Some(Duration::from_millis(100)))
    .on_diagnostic(|ev| tracing::info!(?ev))   // RAISE NOTICE, slow queries, pool stats…
    .build();

match conn.query_one::<GetUser>((id,)).await {
    Err(e) if e.is_disconnect() => reconnect(),  // connection died → reconnect
    Err(e) => return Err(e),                      // query error → the connection is fine
    Ok(u)  => u,
}

// build.rs
bsql_build::Catalog::from_migrations("migrations")
    .bridge("timestamptz", "chrono::DateTime<chrono::Utc>", "crate::to_chrono")
    .emit()?;

// your one infallible converter — the orphan-proof seam
pub fn to_chrono(ts: bsql::Timestamptz) -> chrono::DateTime<chrono::Utc> { /* … */ }

Speed is half the story; the other half is what the driver lets you do. An honest side-by-side with the Rust field — competitors get credit for what they have.

• #![forbid(unsafe_code)] on every shipped crate; deny(unwrap_used, expect_used).
• The compile-checked path pins each column's PostgreSQL OID at build time — a wrong Rust type for a column is a compile error, and a wrong parameter type is rejected loudly on every binding surface (typed at compile, dynamic at the server, prepared at the client, SQLite by storage class) — never a silent byte-for-byte reinterpretation.
• The build-time check is against your committed migration files (the version-controlled source of truth), not a live-DB introspection that can go stale. An out-of-band ALTER TABLE applied by hand with no migration file is invisible at build time — but a runtime OID guard catches such drift as a classified error on the wire, never a silent wrong value.
• What the checker asks of you in return: name your result columns (SELECT * is rejected — the shape must be explicit), and add a cast where an expression's type is genuinely ambiguous (a bare SUM(x) → SUM(x)::int8, an uninferable expression → expr::type). This is the ergonomic price of typing every column; a plain column, a join, COALESCE, and a cast-annotated aggregate all infer with no annotation.
• What "correct" means, precisely. The compile check proves the query's shape: relation and column names, result-column types, nullability, and the parameter type OIDs. It does not type-check the SQL's operand / cast / value semantics — a WHERE bool_col = 5, a nonsensical CAST, or a value-domain violation is caught by PostgreSQL itself at runtime, loudly and classified (42883 / 42846 / 22P02), never a silent wrong result. So "if it compiles, the query is correct" means its shape and types are correct against your schema; the server stays the authority on operand semantics.
• Non-UTF-8 text is a classified error, never a panic. A text / varchar column carrying non-UTF-8 bytes (e.g. a SQL_ASCII database) decodes to a loud DecodeError (NonUtf8), not a panic and not a lossy substitution — read such a column as bytea if it actually holds binary data.
• Large results are bounded and streamable. An eager query / query_raw reads the whole result into one arena bounded at 4 GiB (a larger one is the loud RowTooLarge, never an unbounded OOM); for a colossal result, stream it row-by-row in constant memory with query_each / query_each_raw.
• The wire decoders are proven total (no panic on any input) by a dep-free fuzz gate; the inbound hot dispatch is proven panic-free and byte-stable by a codegen gate. NULL is Option<NonZeroU32>; SQL identifiers spliced into DDL go through a validate-only SafeIdent newtype.
• Over TLS, SCRAM-SHA-256-PLUS channel binding (opt-in-strict) anchors auth to the server's certificate, closing the valid-cert relay/MITM gap that cert + hostname verification alone leaves.
• 64-bit Linux / macOS / Windows. TCP everywhere; unix sockets on unix.

No CI — by design. All gates run locally via cargo and a bsql-devgates crate (dependency-frontier pin, runtime-vs-build boundary pin, intra-doc-link wall, cross-platform check, hot-path codegen ceiling, decoder fuzz):

cargo clippy --workspace --all-targets    # lint wall — 0 warnings
cargo test   --workspace                  # unit + integration (offline)
cargo test -p bsql-devgates               # the pins + walls
# live suites are #[ignore] and need a local PostgreSQL:
cargo test -p bsql-postgres-async --test sq_live -- --ignored

Benchmarks + their methodology live on the bench branch (git switch bench && cargo bench), kept off the code branch so a normal clone stays lean.

Built with Claude and Gemini in adversarial dual-LLM pair engineering. Both systems collaborated continuously across architectural synthesis, red-team chaos auditing, adversarial judging, and zero-overhead implementation — every slice challenged and verified before it landed.

2,640+ tests across the workspace — unit, integration, compile-fail (trybuild), live-database, dependency-free fuzz, and machine-checked codegen gates. Not just tests that the code works, but tests that broken code is rejected at compile time. Hardened by a real-load fault-injection pass (TLS byte-fragmentation, mid-stream faults, million-row streams, concurrency) — the sort of thing that catches what green unit tests hide.

Don't follow the author's name. Don't assume an older library is automatically the safer bet. Run the benchmarks yourself, read the tests, check the code.

CLAUDE.md is the exhaustive engineering reference (conventions, layout, every gate and safety invariant) — read it if you want the full picture.

MIT OR Apache-2.0, at your option.