Expand description
kevy-sql — the OUT-OF-ENGINE, declaration-time SQL compiler.
This tool compiles a schema ONCE, at declaration time, into explicit
kevy engine commands (TABLE.DECLARE, VIEW.CREATE) plus query
cards — ready-made IDX.QUERY templates an application binds
parameters into at runtime. It is a build step, like a schema
migration tool. Nothing here ever runs per-query inside a serving
process: ad-hoc runtime SQL stays refused by the engine itself
(unknown command), and this compiler refuses — by name, with
line/column — every SQL construct that would need query-time
evaluation (JOIN, subqueries, GROUP BY, expressions…). That is
kevy’s Law 3: meaning and planning never enter the engine.
The honest pitch: your schema’s access paths, compiled — not a
drop-in PG. CREATE TABLE becomes a typed, verifiable
TABLE.DECLARE; CREATE [UNIQUE] INDEX becomes declared Range /
Unique / composite ORDERPATH access paths; single-table
CREATE VIEW … AS SELECT becomes either an engine view (constant
predicates) or a query card (parameterized / clause-bearing). The
compiler never plans: a WHERE clause either matches a declared
access path (leading-prefix rule) or the compile errors naming the
exact declaration to add.
let sql = "
CREATE TABLE users (id bigint PRIMARY KEY, email text);
CREATE UNIQUE INDEX ON users (email);
";
let c = kevy_sql::compile(sql).unwrap();
assert_eq!(c.commands[0][0], "TABLE.DECLARE");
println!("{}", c.render_script());Structs§
- Card
Param - One
$Nparameter slot of aQueryCard, with the column it binds and that column’s declared type. - Compilation
- The result of
compile: engine commands, query cards, and notes. - Folded
- One folded statement: the column values of the single result row. Typed, not pre-rendered — the CLI prints PG text forms while the probe runner follows sqllogictest’s conventions (booleans as 1/0), and neither should pay for the other’s rendering.
- Plan
- A migration plan: what to declare, and what becomes of each query.
- Plan
Entry - One query’s row in the plan.
- Query
Card - A compiled runtime template: the exact
IDX.QUERY …argv with$Nslots left in place. The application substitutes real values for the slots and sends the argv as-is — there is no runtime SQL. - SqlError
- A compile error, anchored to the source:
line N, col C: message.
Enums§
- Kevy
Type - A kevy column type — the deliberately coarse target of the SQL type
mapping (kevy columns are
i64 | f64 | str; timestamps and the like are app-encoded strings). - Scalar
- A typed scalar value — the closed set the function library speaks.
- Served
- Whether a declared query can be served, and by what.
Functions§
- compile
- Compile a whole SQL schema file into a
Compilation. - fold_
select - Evaluate a table-free
SELECT expr[, expr…];against the given clock (epoch microseconds). Refusals areSqlErrors whose text names the construct — never a silent wrong answer. - plan
- Plan a whole SQL file: DDL becomes declarations, each
CREATE VIEWbecomes an entry saying whether it can be served and by what.