Skip to main content

Crate kevy_sql

Crate kevy_sql 

Source
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§

CardParam
One $N parameter slot of a QueryCard, 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.
PlanEntry
One query’s row in the plan.
QueryCard
A compiled runtime template: the exact IDX.QUERY … argv with $N slots 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§

DeclarationError
Why crate::table_ddl refused a declaration: it does not read as a TABLE.DECLARE, or it names something SQL text cannot spell.
Scalar
A typed scalar value — the closed set the function library speaks.
Served
Whether a declared query can be served, and by what.
ValType
Declared scalar type of an index (TYPE i64|f64|str).

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 are SqlErrors whose text names the construct — never a silent wrong answer.
plan
Plan a whole SQL file: DDL becomes declarations, each CREATE VIEW becomes an entry saying whether it can be served and by what.
select_card
One SELECT … FROM t WHERE … as the IDX.QUERY argv that answers it over t’s declared paths. Values are literals; a $N slot is a card parameter and is refused here (that is sql compile’s shape). A query no declared path serves is refused with the same text sql plan gives it. Never an engine view: a view is a declaration, and this answers a query now.
table_ddl
A TABLE.DECLARE argv as the SQL sql compile turns back into the same declaration: CREATE TABLE, then one CREATE [UNIQUE] INDEX per index and order path, in declaration order. What SQL has no words for — a key prefix other than <table>:, WINDOW, AUTODECLARE, a one-column order path — is written as a -- comment naming the clause, so a reader sees what the SQL form does not carry.