keelson

for a reader with something specific to get done

How-to

Fourteen tasks. Each one is answered by a program that runs, asserts its own output, and is executed by keelson's CI — so the answer is never a snippet that used to work.

Clone the repository and run any of them; none needs a database server, because the ones that touch a database use SQLite in a temporary file that is deleted afterwards.

git clone https://github.com/ken109/keelson-rs
./scripts/run-examples.sh   # or one at a time, below
Layer 15 tasks

  • See the SQL before any database is involved

    A statement is a starter plus mods. SELECT/INSERT/UPDATE/DELETE, and the difference between an identifier, a literal and a bound value.

    examples/builder_basics.rs ↗cargo run -p keelson-examples --example builder_basics

  • Apply a filter that is only sometimes there

    Option<M>, Vec<M> and () are all mods, so a condition decided at run time drops into the same tuple — no string assembly, no second query builder.

    examples/dynamic_queries.rs ↗cargo run -p keelson-examples --example dynamic_queries

  • Write the parts of SELECT past WHERE

    Joins, aggregates, CTEs including recursive ones, sub-queries, window functions, DISTINCT ON.

    examples/joins_and_ctes.rs ↗cargo run -p keelson-examples --example joins_and_ctes

  • Use a construct only one engine has

    One upsert written three times. MERGE, REPLACE, INSERT OR REPLACE — and why keelson_mysql has no returning to call.

    examples/dialects.rs ↗cargo run -p keelson-examples --example dialects

  • Mix in SQL you wrote yourself

    A whole hand-written statement run through the same verbs, fragments inside a built statement, and what a refusal looks like.

    examples/raw_sql.rs ↗cargo run -p keelson-examples --example raw_sql
Layer 24 tasks

  • Run a statement and map the rows

    fetch_all / one / optional / scalar / execute, #[derive(FromRow)], and passing a &dyn Executor around.

    examples/execute.rs ↗cargo run -p keelson-examples --example execute

  • Decide who owns the transaction

    The closure form, savepoints, Atomic units of work that nest wherever they are called, isolation levels, and the refusals.

    examples/transactions.rs ↗cargo run -p keelson-examples --example transactions

  • Read a result set one row at a time

    Streaming instead of collecting, and what holds the connection while you do.

    examples/streaming.rs ↗cargo run -p keelson-examples --example streaming

  • Find out what a failure will look like

    Every error keelson can hand you, provoked on purpose and printed.

    examples/errors.rs ↗cargo run -p keelson-examples --example errors
Layers 3–44 tasks

  • Query through generated models

    Typed columns, the three-state Setter that tells unset from NULL, hooks, and a view model.

    examples/models.rs ↗cargo run -p keelson-examples --example models

  • Load relations without N+1

    preload (one LEFT JOIN in the same query) against then-load (one batched, keyed query per level), and how levels chain.

    examples/relations.rs ↗cargo run -p keelson-examples --example relations

  • Make test data

    Factories with auto-created parent chains, sequence-based uniqueness, and a seedable faker.

    examples/factories.rs ↗cargo run -p keelson-examples --example factories

  • Compile a .sql file into typed Rust

    Each query gets two faces: one that runs the file's own SQL, and one that merges its clauses flat into a model query.

    examples/sql_files.rs ↗cargo run -p keelson-examples --example sql_files
Putting it together1 task

  • Put a repository and a usecase together

    A repository called standalone and inside a usecase's transaction, where the boundary belongs, and the pool-in-a-field trap.

    examples/repositories.rs ↗cargo run -p keelson-examples --example repositories
what refuses to compile
The examples show what keelson does; tests/compile_fail ↗ shows what it refuses, as nine programs that must fail to build — a column the schema lacks, a typed comparison against the wrong Rust type, RETURNING on MySQL. Each sits next to the error it has to produce.