A SQL toolkit for Rust that never hides the SQL.

1. 01

   Query builder

   Statement starters — select, insert, update, delete, merge — filled in by mods: values that modify a statement. A tuple of mods is itself one mod, so composition never runs out of arity, and a raw &str is an expression anywhere one is accepted.

   • keelson-core
   • keelson-psql
   • keelson-mysql
   • keelson-sqlite

   let q = psql::select((
       select::columns((quote("id"), quote("name"))),
       select::from(quote("crew")),
       maybe_filter,                  // Option<M> is a mod; None adds nothing
       select::where_("name IS NOT NULL"),  // raw &str, same tuple
   ));
   
   let (sql, args) = q.build()?;      // synchronous, driver-free

2. 02

   Execution

   An object-safe Executor — a pool, a connection, a transaction, a &dyn Executor — and the Execute verbs on every query. Transactions are closures with no lifetime to thread: within commits on Ok and rolls back on Err, and the closure gets a &Transaction it cannot commit twice or forget to commit.

   • keelson-exec
   • keelson-sqlx

   let crew: Vec<Crew> = q.fetch_all(db).await?;
   
   // A savepoint is a closure too: Ok releases it, Err rolls back
   // to it, and the outer transaction lives on.
   db.within(async |tx| {
       insert_tag(tx, "kept").await?;
       let _ = tx.savepoint(async |tx| bulk_load(tx).await).await;
       insert_tag(tx, "also kept").await?;
       Ok::<_, ExecError>(())
   })
   .await?;

3. 03

   Models

   A typed shell per table or view. users::age() is one Column<i64> that is the expression, the filter origin and the alias carrier at once. A three-state Setter tells “leave the column alone” apart from “write NULL”. Relations load by same-query preload or by chained, batched then-loads — never lazily.

   • keelson-models
   • keelson-factory

   let adults = users::table()
       .query((
           users::age().gte(21),      // typed: .gte("x") will not compile
           select::where_(r#""users"."name" <> 'bob'"#),  // raw, same tuple
           select::order_by(users::age()).desc(),         // Layer 1 mod
           users::then_load::posts(), // one batched IN query per level
       ))
       .all(db)
       .await?;

4. 04

   Generation

   A CLI, not a proc macro: it introspects a live schema and writes .rs files you commit, diff and step through. It also compiles hand-written .sql files into typed modules — and each query has two faces, one that runs the file's own SQL and one that merges its clauses flat into a model query instead of nesting as a sub-select.

   • keelson-gen

   cargo install keelson-gen
   keelson-gen --config keelson.toml --url "$DATABASE_URL"

psql::insert((
    insert::into(quote("users")).columns(["email", "name"]),
    insert::values((arg("ada@example.com"), arg("Ada"))),
    insert::on_conflict(quote("email"))
        .do_update(insert::set_excluded(["name"])),
    // PostgreSQL hands the written row back, so a write is one round trip.
    insert::returning((quote("id"), quote("name"))),
))

INSERT INTO "users" ("email", "name") VALUES ($1, $2)
ON CONFLICT ("email") DO UPDATE SET "name" = EXCLUDED."name"
RETURNING "id", "name"

The cost is real. You cannot build one statement and render it for whichever database the customer brought — keelson makes that impossible by construction. What it buys is constructs a common denominator cannot express, and the guarantee that what compiles is grammatical for the engine you compiled it for.

• grammar

  Each dialect is written to its own grammar.

  There is no shared AST that every database is squeezed through. keelson-psql's SELECT is shaped by PostgreSQL's own reference manual, keelson-sqlite's by SQLite's railroad diagrams, keelson-mysql's by MySQL's. Clauses that genuinely coincide are shared through traits — but a construct only one engine has is only on that engine, and a construct it lacks is not offered.

  docs/sql-rendering.md ↗
• proof

  Everything that renders SQL is judged by a real parser.

  Expected SQL in the tests is derived from the official grammar and checked with the engine's own parser — PostgreSQL's libpg_query, SQLite's lemon grammar — and, in the engine tier, PREPAREd by a real containerised server. A coverage gate then proves that every construct the library declares was actually exercised.

  docs/testing-tiers.md ↗
• refusal

  Anything unsupported is an explicit error.

  No silent fallback, no plausible guess. If MySQL cannot honour a read-only transaction the way you asked, you get a refusal that names the engine's rule — not a downgrade. SQLite cannot run READ COMMITTED, so it refuses that isolation level rather than pretending it applied.

  docs/execution.md ↗
• legibility

  Generated code is meant to be read.

  keelson-gen is a CLI that writes .rs files you commit and diff, not a proc macro that expands somewhere you cannot step through. Every nullability decision in a generated query module is written into the file as the numbered rule that made it.

  examples/ ↗