Architecture & Request Flow

A map of how a query travels from your fluent call to the database and back. File references point at the real definitions so you can jump in and read the body.

Layers (who depends on whom)

The key idea: core never names a concrete driver type. Backend.jl declares backend_* generics; the real bodies live in the ext/ weak-dependency extensions, loaded only when LibPQ, Postgres, SQLite or MySQL is present. A PostgreSQL pool names its driver (postgres_driver:), so the LibPQ and Postgres.jl extensions coexist.

Read path — the query lifecycle

The two things worth internalizing:

1. Lazy until a terminal. filter/values/order_by/... only mutate the SQLObjectQuery. No SQL exists until a terminal (list/first/get/count/exists/create/update/delete) calls query().
2. Sync wraps async. fetch() is a thin wrapper over fetch_async(). The pool is guarded by a ReentrantLock; the connection is returned to the pool in await_result once the rows are materialized.

Terminals — read vs write

Every terminal funnels through the same build → parameters → Dialect → fetch machinery; only the clause it emits (SELECT vs INSERT vs UPDATE vs DELETE) differs.

Migrations — a separate flow

State-based reconciliation: compare model definitions against the live schema, emit DDL, track it.

Known architectural edges

The macro-structure above is sound — Django-shaped layers and a clean backend seam. A skeptical audit turned up no outstanding confirmed correctness bugs; the notes below are maintainability characterizations worth stating plainly.

Maintainability edges (no correctness impact)

• Model-load lifecycle (the one genuine flow gap) — #65. FK / one-to-one / many-to-many / CTE target resolution happens lazily and ad-hoc in several places (the join builder resolves bindings inline via getfield(module, …) / invokelatest, M2M scans all models, CTEs resolve their own way). There is no single "load + resolve" pass between models defined and queries/migrations run (Django's apps.populate() analog). Highest-leverage improvement — it removes why the join builder does resolution inline, and retires the world-age-risky reflection.

• Join builder shape — #68 and #487, both landed. The join plan is typed: row_join is a Vector{JoinRow} whose four kinds — ModelJoin, CteJoin, CrossJoin, AnchorlessJoin (src/querybuilder/types.jl) — select the render path by dispatch rather than by string flags. _build_row_join resolves the first hop and each subsequent hop through one _forward_fk_hop / _reverse_hop / _finish_hop! triple (src/querybuilder/build_joins.jl), so the db_column key resolution has a single source of truth per hop direction; the CTE arm is first-hop only by design, and the many-to-many arms fold their own tail.

• Type stability is structural, not cosmetic — #41. The query state is built on Dict{String, Any} + heavy Union fields, the fluent API dispatches via a runtime sym === :filter ladder, SQL rendering runs through getfield(Module, Symbol(...)) reflection per query, and fetch returns Any. This is baked into the core types — not fixable in function bodies. Honest nuance: low-leverage for runtime latency (it runs once per query to produce a string), but it drives TTFX/allocations and the invokelatest world-age fragility on the join path.

• Positional-parameter buckets (deliberate, contained) — for SQLite and MySQL the positional ? markers are collected into per-clause buckets and flattened in SQL-clause order (:cte → :select → :update → :join → :where → :group → :having → :order → :limit). The flatten order is single-sourced in _BUCKET_ORDER (which get_final_parameters and the nested-run machinery both read) and guarded by test_alignment_sqlite.jl / test_parameters.jl. Noted here so it is not mistaken for accidental coupling.

  Two costs, not one. Adding a new bucket is a documented multi-site edit (see the QueryBuilder skill's maintenance checklist). The subtler one: a bucket is chosen by the builder phase that binds a value, while correctness depends on where that value's ? is emitted — and those diverge whenever a fragment renders somewhere other than its own clause. Three bugs came out of that gap — #421 a relocated fragment (unrepresentable since #982: a join condition renders on its own row, in emission order) and #432 a nested render, both SQLite-only, plus #441 a discarded projection, whose parameter desync was SQLite-only but which dropped the column itself on both backends. All three were silent. A nested render now re-emits its values as one clause-ordered run at its own marker position (nested_parameter_mark / detach_nested_run!). All four such sites in the read builder go through it — Exists, a projected Subquery, an __@in subquery, and a CTE body.

  deletion.jl splices one row predicate per cascade path into a hand-built DELETE/UPDATE (_collector_predicate). Since #765 each is the path's filters on the target row — and, when they cross a join, "Tb"."pk" IN (<selection>) AND EXISTS (<fence>), two builds of the same query: the IN for the index-driven plan, the correlated EXISTS because PostgreSQL does not re-check a pk IN (SELECT …) self-subquery under a row lock. Every build goes through the same machinery, so the claim is "contained" there too — and there the wrap is load-bearing: a joined root's two builds both bind their ON values in :join, which unwrapped would flatten both ahead of the first build's WHERE values (text order is ON₁ WHERE₁ ON₂ WHERE₂). Before #765 it was insurance only — no statement ever held two join-binding fragments, since every cascade arm is a bare filter("<fk>__@in" => parent) with no join of its own, and that is still true of cascade arms. update()'s joined branch does the same with its top-level build as the selection and one lifted fence build behind it.

Where to look next