kevy-sql
Your schema's access paths, compiled — not a drop-in PG.
kevy-sql is a declaration-time SQL compiler for kevy: it reads a PG/MySQL-flavoured schema file ONCE — like a migration tool — and emits explicit kevy engine commands plus ready-made query templates:
CREATE TABLE→ oneTABLE.DECLARE(typed columns, PK, prefix);CREATE [UNIQUE] INDEX→ declared Range / Unique access paths; multi-column indexes → compositeORDERPATHs; PG-styleINCLUDE (…)covering columns → storedVALUESfor residual FILTER/SORT;- single-table
CREATE VIEW … AS SELECT→ an engineVIEW.CREATE(constant predicates) or a query card: the exactIDX.QUERY …argv with$Nslots your app fills at runtime.
Nothing here ever runs per-query inside a serving process. Ad-hoc runtime SQL stays refused by the engine itself (unknown command) — that is kevy's Law 3: meaning and planning never enter the engine.
$ kevy-cli sql compile schema.sql # print the compiled script
$ kevy-cli sql compile schema.sql --apply --url 127.0.0.1:6004
Or as a library:
let c = compile?;
for argv in &c.commands
println!;
# Ok::
The compiler never plans
A view's WHERE either matches a declared access path (single-column
index, INCLUDEd stored columns, or a composite index by the
leading-prefix rule) — or the compile errors naming the exact
declaration to add:
line 9, col 1: view 'v': WHERE (dept EQ, age range) matches no declared
access path — add: CREATE INDEX ON emp (dept, age)
Deterministic path choice (no cost model, no statistics):
- constant predicates + expressible ORDER BY → an engine view;
- all predicates on one indexed column → a direct-drive card;
- the predicate set is a leading prefix of a composite index → a
WHEREcard on that ORDERPATH; - else the first indexed predicate drives and residuals compile to
FILTERover the index'sINCLUDEcolumns — or the error names what to add.
What refuses, and how
Everything outside the subset errors by name, with line/column, and the message teaches the kevy-shaped alternative instead of just saying no:
line 12, col 3: JOIN is not compilable — kevy refuses query-time joins
(Law 3); model the lookup with an indexed FK column (IDX.QUERY t.fk EQ …)
or app-side assembly (cookbook §2)
JOIN, subqueries, OR, GROUP BY/HAVING, expressions and function calls,
!=, LIKE, IS NULL, NOT NULL/DEFAULT/CHECK/FOREIGN KEY constraints,
INSERT/UPDATE/DELETE/ALTER — all named refusals.
The coarse type mapping (honest)
kevy columns are i64 | f64 | str — nothing else:
| SQL | kevy | note |
|---|---|---|
| int, integer, bigint, serial, bigserial | i64 |
serial does not auto-increment — allocate ids app-side |
| real, float, double precision, numeric, decimal | f64 |
fixed-point becomes binary float; keep money as integer cents |
| text, varchar(n), char(n), uuid | str |
length limits are not enforced |
| timestamp, timestamptz, date | str |
app-encoded; use a sortable encoding (RFC3339 / zero-padded epoch) |
| bool, boolean | str |
store '0'/'1' |
| json, jsonb | str |
flatten indexed paths to their own columns |
The compiler emits a note per lossy column so the mapping is never silent.
Grammar (subset v1)
script = { statement ";" } ;
statement = create_table | create_index | create_view ;
create_table= "CREATE" "TABLE" name "(" item { "," item } ")" ;
item = column type [ "PRIMARY" "KEY" ]
| "PRIMARY" "KEY" "(" column ")"
| "UNIQUE" "(" column ")" ;
create_index= "CREATE" [ "UNIQUE" ] "INDEX" [ name ] "ON" name
"(" column [ "ASC" | "DESC" ] { "," column [ "ASC" | "DESC" ] } ")"
[ "INCLUDE" "(" column { "," column } ")" ] ;
create_view = "CREATE" "VIEW" name "AS" "SELECT" ( "*" | column { "," column } )
"FROM" name "WHERE" pred { "AND" pred }
[ "ORDER" "BY" column [ "ASC" | "DESC" ] ]
[ "LIMIT" int [ "OFFSET" int ] ] ;
pred = column ( "=" | ">" | ">=" | "<" | "<=" ) value
| column "BETWEEN" value "AND" value ;
value = number | "'" string "'" | "$" int ;
Keywords are case-insensitive; unquoted identifiers fold to lowercase
(PG's rule); "quoted" identifiers keep their case; -- and /* */
comments; '' escapes inside strings. Strict > / < compile exactly
on integer literals (±1) and refuse elsewhere — RANGE bounds are
inclusive, and a silent off-by-epsilon would be an approximation, not a
compilation.
Part of the kevy workspace; pure Rust, zero crates.io dependencies
(the runtime crate is pure std).