keelson

for a reader with why it is shaped this way

Explanation

keelson's reasoning is written down where the code is, in documents that record the decision and the alternative it beat. This page says which one answers which question.

Start with the README ↗ if you have not: it holds the four properties that hold across every layer, and a section arguing for sqlx, diesel, SeaORM, sea-query and cornucopia over keelson wherever they are the better answer. Then each crate's src/lib.rs carries its own architecture notes — that is the intended place to read before changing one.

documents

  • How a statement becomes SQL

    docs/sql-rendering.md ↗

    You want to know where the quoting, the placeholders and the one-pass rule come from — or you are writing a dialect crate.

  • The execution layer's decisions

    docs/execution.md ↗

    The longest document here, and the one to read before changing Layer 2. Each question is answered once, with the alternative that was rejected written down next to it.

  • What each tier of tests proves

    docs/testing-tiers.md ↗

    You are wondering how much the green checkmark is worth. Four tiers, ending in real engines PREPAREing every statement, plus a gate that proves every declared construct was exercised.

  • Why a type maps the way it does

    docs/type-mappings.md ↗

    A column is not decoding the way you expected, or you are adding a Value variant.

  • Views, and what they cannot do

    docs/views.md ↗

    You are generating models over views and hit the updatability rules.

  • The crate graph and the release

    docs/publishing.md ↗

    You are cutting a release, or wondering why keelson-sqlcheck is not on crates.io.

the one to read first
If you only read one, read docs/execution.md ↗. It is where the shape of the library is actually argued — why a transaction is a closure, why an unsupported isolation level is a refusal rather than a downgrade, and what each of those cost.