Reylo v0.8.0
Reylo v0.8.0 introduces the reylo CLI, which installs without Node, along with deeper inference and more drivers.
It has a number of breaking changes from v0.7, listed in Upgrading from v0.7.
The reylo CLI
The reylo CLI installs from npm, or without Node through Homebrew, Scoop, Docker or a script (#174, #275).
brew install reylosql/tap/reylo # Homebrew
curl -fsSL https://reylo.dev/install.sh | sh # macOS and Linux
irm https://reylo.dev/install.ps1 | iex # Windows PowerShell
scoop bucket add reylo https://github.com/reylosql/scoop-bucket && scoop install reylo
docker run --rm ghcr.io/reylosql/reylo --versionEvery route installs the same binary:
- Checked: the install scripts, Homebrew and Scoop check the binary against the release's
SHA256SUMS - Platforms: macOS, Linux on glibc and musl, and Windows, each on x64 and arm64
Statement analysis
The new reylo analyze prints what Reylo infers for each statement, as YAML or as JSON with --format json (#172, #239).
file: queries/get_user.sql
$schema: https://reylo.dev/typedefs/preview.json
dialect: { name: postgres, version: "18.6" }
sql: |
-- One user, by id.
select id, email, bio from users where id = $1
kind: select
comment: One user, by id.
params:
- name: id
type: { kind: integer, bits: 64, label: int8 }
result:
kind: table
cardinality: at_most_one
columns:
- name: id
type: { kind: integer, bits: 64, label: int8 }
- name: email
type: { kind: text, code_points: [[1, 1114111]], size: { max: 255 }, label: varchar }
- name: bio
type: { kind: text, code_points: [[1, 1114111]], label: text }
nullable: true
comment: Shown on the profile page
capabilities:
tables: { public.users: read }
diagnostics: []Besides each type, it reports what the database declares and what Reylo infers about it:
- From code:
analyze(), exported fromreylo, returns the same descriptor (#191, #195) - Sizes and precision:
varchar(20)issize: { max: 20 }, andnumeric(10,2)carries its precision and scale (#180, #192, #210) - Check constraints:
check (age between 0 and 150)givesminandmax, andcheck (slug like 'a%')apattern(#200, #251) - UUID versions:
gen_random_uuid()is version 4 anduuidv7()version 7 (#232) - Unique columns and order: a result's
uniquecolumn sets, and theorderits rows are sorted on, on Postgres (#184, #213) - Distinct arrays:
array_agg(distinct …)andjson_agg(distinct …)are markeddistinct(#251)
Structured values
Postgres's structured values, and MySQL's SET, now come back as objects (#193, #197, #205).
- Row value:
"(1,Ada)"→{ id: 1, name: "Ada" } - Geometric type:
"(1.5,-2)"→{ x: 1.5, y: -2 } - Range:
"[1,5)"→{ lower: 1, upper: 5, bounds: "[)" }, or{ empty: true } - Multirange:
"{[1,3)}"→ an array of ranges - Array of a subquery's rows:
array(select c from (…) c)→ an array of objects, each field decoded - MySQL
SET:"a,c"→new Set(["a", "c"]) - MySQL
ENUM: typed as the union of its labels, where it wasstring
Parameters take the same forms.
Deeper inference
Reylo now reads SQL function bodies and infers through keyed writes, constants, whole rows and RETURNING.
update t set note = :note::text where id = :id returning noteThe returned note is a string, where it was nullable (#267).
- SQL function bodies: a Postgres
language sqlfunction's body is read as its query, soselect id, body from one_comment(:x)is one row of non-null columns (#211) - Keyed writes: an
update … fromordelete … usingthat pins a key returns a row ornull, and so does an insert of one selected row (#190) - Constants: a column a statement fills with constants is typed as those literals, such as
"user" | "post"(#243) - Whole rows: a whole row of a derived table, subquery,
withquery or aliased join is typed field by field (#167) - Arrays: each level of an array of arrays is typed, and
array_remove(tags, null)or aCHECKthat keepsNULLout makes elements non-null (#181, #166, #287) - Check constraints:
tags <@ array['a', 'b']types("a" | "b")[], andjsonb_typeof(doc) = 'object'types an object (#190, #171) - Triggers: a
BEFOREtrigger whose everyreturnisnew, such as anupdated_attrigger, no longer makes a write nullable (#190) - Grouped JSON: an object that puts an aggregate beside a grouped column is typed inside a scalar subquery, and on MySQL at the top level (#230)
- SQLite views: a write to a view through its
INSTEAD OFtrigger type-checks (#238) - libSQL vectors: on a Turso project's local file, the type check reads vector columns and indexes, the vector functions and
vector_top_k(#316) - Postgres 19: supported, and tested in CI (#311)
- Shorter setup:
"contentMappers": [{ "package": "reylo" }]is enough on TypeScript's 7.1 nightlies from 2026-11-12 on (#315)
More drivers
Queries now run on Knex, SQLite Wasm and sql.js, and on mysql2 through Cloudflare Hyperdrive.
import knex from "knex";
import getUser from "./get_user.sql";
const db = knex({ client: "pg", connection: process.env.DATABASE_URL });
const user = await getUser.run(db, { id: 1 });The clients it adds:
- Knex: an instance, transaction or savepoint, over
pg,mysql2,mariadb,better-sqlite3andsqlite3(#233) - SQLite Wasm: an
oo1database of@sqlite.org/sqlite-wasm, OPFS ones included (#235) - sql.js: a
Databasefrom sql.js 1.17.0 on (#331) - Hyperdrive:
mysql2, and Drizzle or Knex over it, through Hyperdrive, which refuses prepared statements (guide, #261, #284) - Durable Objects: a Workers project with Durable Objects and no D1 database is type-checked on Cloudflare's SQLite (#241)
Standard Query
A built module's Standard Query carries more of what Reylo infers, for drivers that run it themselves.
- Decoders:
columnsholds a decoder per column, andoutput()applies the cardinality to decoded rows (#165) - Keys:
keynames the result columns that identify each row, on Postgres (#160) - Order:
orderedistruewhere theorder bymakes the order total, on Postgres (#163) - Cardinality:
cardinalitysays how many rows the statement returns (#206) - Reads:
readOnlyistruewhere nothing in the statement can write (#190) - Schemas:
inputSchemaandoutputSchemacarrymaxLength,pattern, bounds,multipleOf,enumanddescription(#199, #192)
Faster and smaller
A bundle now carries only its query's dialect, and the type check reads the catalog once per run.
- Bundle: 162.8 KB for every dialect → Postgres 76.7 KB, MySQL 117.7 KB, SQLite 63.2 KB, for one query built minified by esbuild 0.28.2 (#228)
- JIT off on the engine's Postgres connections: 264 s → 20 s over 566 statements, where JIT is on, as in the official Docker images (#158)
- Catalog read once per run: 10.29 s → 6.01 s over 517 statements (#190)
- Postgres row decoding: 13.5 → 16.8 reads per second of 25,000 rows × 12 columns through postgres.js (#164)
- Inserts of
::rows: 91 ms → 63 ms for 10,000 rows into a 20-column table (#277) - A SQLite
CASEof 10,000 arms: 7.2 s → 0.45 s (#238) - Vite, Rollup and Rolldown: the plugin's hook filters skip every module that isn't
.sql(#137)
Docs
The docs at reylo.dev now describe v0.8:
- A homepage: reylo.dev, with the docs at reylo.dev/docs (
ce24aa1) - Pages with a sidebar: guides for Cloudflare D1 and Durable Objects, Neon, PlanetScale, Supabase, Turso, Next.js and CI (
c451fed,381daa1,8de0c6e) - Reylo Migrate: a page of its own, with its docs under it (
bc22e61,ba3e060) - Cloudflare Hyperdrive: a guide to Postgres and MySQL through it (
e7288e7) - A comparison with other SQL tools, each mark from a real run (#183)
- Moving from Prisma: a guide (
d3940d3)
Upgrading from v0.7
Each change below can surface in a project that upgrades from v0.7.
Every dialect
- One unnamed column returns its values, not rows. Write
const count = await q.run(db), or addas countto keep a row (#206). - Columns filled with constants are typed as their literals. Widen the variable's type where code assigns another value to it (#243).
- A JSON column whose schema leaves
additionalPropertiesout has no index signature. Name the key in the schema, or giveadditionalPropertiesa schema (#169). - An untyped JSON parameter is
JsonInput, notunknown. Type the value passed to it asJsonInput, exported fromreylo(#193). - The command
reylo generateno longer fills the cache, and the project file'sclisection was removed. Drop it from scripts and CI, and deletecli:(#174). - The setting
strict_paramsis nowallow_untyped_params, which reads the other way round. Writeallow_untyped_params: trueforstrict_params: false, and deletestrict_params: true(#187). - The cache moved from
.reylo/toreylo/.cache/. Delete.reylo/and its.gitignoreline (#179). - An unquoted
.envvalue is cut at its first#, as dotenv reads it. Quote the value, or write#as%23(#227). - A hand-written
{ query }client wrapper is refused. Pass the driver's own pool, client or transaction, or subclass or proxy it (#242). - A build that can't reach its database reads only that server's analysis. Unset the URL for a build that relied on another database's analysis (#242).
- The run-time schema check was removed. Build again after each migration, since nothing warns when a build is older than its database (#208, #306).
- A query made with
defineQuerysends itssqlas written. Give a statement with:nameplaceholders its compiledtextandorder(#306). - A value with no time zone carries no
format: date-timeorformat: timein a query's JSON Schema. Validate it without the format (#306).
Postgres
- Row values, geometric types, ranges, multiranges and arrays of a subquery's rows come back as objects. Remove the code that parsed their text (#193, #205).
- The values
NaNandInfinityinside built JSON are numbers. Test them withNumber.isNaNandNumber.isFinite(#171). - A timestamp always has six fraction digits. Update code or tests that compare its text (#190).
- A
moneyvalue comes back as its decimal text,"1234.50". Format it for display in the app (#254). - A keyed write, an insert of one selected row, a keyed function call and a
CALLwithOUTparameters return a row, not an array. Check the row fornullinstead of reading.length(#190, #211, #186). - An array of more than one dimension in a column or in built JSON is refused. Select
to_jsonb(column), or setallow_nested_arrays: true(#181, #243). - The setting
ssl=truechecks the certificate and its name. Usessl=no-verifyorsslmode=requirefor an unchecked connection (#226). - A date under a non-ISO
DateStylemakes.run()throw. Setdatestyle = 'ISO, DMY'on the database or the connection (#242). - Some columns widen to nullable or to any JSON. Handle
nullwhere the type check now asks (#225, #226, #273, #306).
MySQL
- A
SETcomes back as aSet. Remove the code that split its text, and pass aSetas a parameter (#193). - An
ENUMis typed as its labels, and an empty''value is refused. Read such a column withnullif(column, '')(#193). - A made-up column name that isn't an identifier, beside other columns, is an error. Name the column with
as(#206). - A JSON parameter where MySQL takes a value, as in
json_set(doc, '$.name', :name), is an error. Write:name::jsonwhere the error points (#242). - Some columns widen to
unknownor toint | bigint. Handle the wider type where the type check now asks (#226, #234, #306). - The type check needs MySQL 8.0.38 or later. On an older server it crashes the server or never returns (#306).
- Through
query(), as on Hyperdrive, a statement whose reading turns onsql_modeis refused under another mode. Run it under thesql_modethe build used (#306).
SQLite
- A made-up column name that isn't an identifier, beside other columns, is an error. Name the column with
as(#206). - A double-quoted string,
select "hello", fails the type check, as most SQLite drivers refuse it. Write string literals in single quotes (#215). - A parameter the lexer doesn't read, such as
:été, is an error. Rename the parameter (#226). - A
bigintparameter outside the 64-bit range throws before the statement runs. Pass a value in range (#268, #274). - Some columns widen to nullable. Handle
nullwhere the type check now asks (#225, #238, #306).
DuckDB
- DuckDB support was removed. A
duckdb:URL is refused, anddefineDuckdbQuery,DuckdbClientandDuckdbQueryErrorare gone, so stay on v0.7 for a DuckDB project (#258).