reylo README

The project's README from github.com/reylosql/reylo. As one markdown file: README.md.

Reylo

Import .sql files into your TypeScript code with full type inference

test status License: MIT npm version GitHub stars

Read the docs →

An editor: hovering a query's result shows its type, which follows the SQL as the SQL changes


If you have a file like this:

-- get_author.sql
select u.id, u.name, count(p.id)::int as post_count
from users u
left join posts p on p.user_id = u.id
where u.id = :id::int
group by u.id

You can import it directly from a TypeScript file like this:

// main.ts
import postgres from "postgres";
import getAuthor from "./get_author.sql";

const db = postgres(process.env.DATABASE_URL);

const author = await getAuthor.run(db, { id: 1 });
// { id: number; name: string; post_count: number } | null

Reylo is powered by TypeScript content mappers, introduced in TypeScript 7.1 (currently in beta), which let you dynamically define static types for external file types and integrate them directly into TypeScript compilation.

Reylo is the perfect option for the agent era:

Setup

To install Reylo, you'll need:

Install Reylo, which brings its engine for your machine, and TypeScript 7.1:

npm install reylo
npm install -D typescript@beta

Add Reylo to tsconfig.json, for .sql files and for its project file, .reylo.yaml or .reylo.yml:

// tsconfig.json
{
  "compilerOptions": { /* ... */ },
  "contentMappers": [
    { "package": "reylo", "extensions": [".sql", ".reylo.yaml", ".reylo.yml"] }
  ]
}

Then type-check with --runExternalCode, which lets tsc run content mappers:

// package.json
{
  "scripts": {
    "typecheck": "tsc --noEmit --runExternalCode"
  }
}

Point Reylo at your dev database with DATABASE_URL, in your environment or in .env. Its scheme tells Reylo which database you use:

# .env
DATABASE_URL=postgres://localhost:5432/app  # or mysql://…, file:./app.db for SQLite, duckdb:./app.duckdb for DuckDB

To make .sql imports work at run time too, load Reylo where your code runs. On Node:

node --env-file=.env --import reylo/register main.ts

For Bun, Nub, Vite, Next.js, esbuild, webpack, Rspack, Cloudflare Workers and Jest, add the plugin for your setup, or copy its complete example project. To see the types as you type, set up your editor.

To give your coding agent Reylo's rules for writing and running queries, install its skill:

npx skills add colinhacks/reylo --skill using-reylo

Usage

Write a query in a .sql file, import it, and run it with your database driver:

-- get_user.sql
select id, name, email from users where id = :id::int
import getUser from "./get_user.sql";

const user = await getUser.run(db, { id: 1 });
// { id: number; name: string; email: string | null } | null

Name each parameter with a colon, and give it a type with a cast where the query doesn't pin one down. Pass .run() your driver's client: a pool, a client, or a connection or transaction taken from one.

It resolves to the rows, shaped by how many the query can return:

The query Resolves to
A match on a primary or unique key, or limit 1 Row | null
An aggregate without group by, a one-row insert … returning Row
An insert, update or delete without returning void
Anything else Row[]

An imported query also has .runSync(), .try(), .with(), .sql, .raw and .source (Usage). Every query Reylo runs is published on Node's tracing channel reylo:query, for a tracer or a logger to subscribe to (Tracing).

What Reylo infers

To type a query, Reylo has your dev database prepare it, without running it, and reads back the type of every column and parameter. On top of that, it infers:

Each has examples in Inference.

Supported drivers

Reylo is bring-your-own-driver. Pass .run() a client from any of these, or a Drizzle database or Knex instance over one:

Documentation

reylo.dev covers the rest: every plugin and editor, configuration, errors, each database's data types and edge cases, and advanced examples. Agents can read it all as Markdown at reylo.dev/llms.txt. To move a Prisma project's queries to Reylo, see Migrating from Prisma.

License

MIT

reylo (reylosql/reylo)

Searching Database…

1.6K ·GitHub
What is this?Reylo lets you import .sql files directly into your TypeScript code and get full type inference for the query's rows and parameters, with no code-generation step.
Is this an ORM or just a typing layer?It is a bring-your-own-driver typing layer, not an ORM: you write raw SQL and still pass your own database client (pg, mysql2, better-sqlite3, etc.) to run queries, Reylo just type-checks and types them.
How do I get it running in a project?Install Reylo, add it to tsconfig.json for .sql files and its project file (.reylo.yaml or .reylo.yml), then type-check with the --runExternalCode flag and point DATABASE_URL at your dev database.
Do I need a specific TypeScript version or a live database?Yes to both: Reylo requires TypeScript 7.1 (currently in beta, the first release with content mappers), Node 24 or later, and a running dev Postgres, MySQL 8.0.22+, or SQLite database it can read the schema from.
Can I use this with the stable TypeScript release today?Not really — Reylo depends on content mappers, a feature that only exists in the TypeScript 7.1 beta, so you're pinned to a pre-release compiler until that version ships.
Which bundlers and runtimes does it plug into at runtime?Node works out of the box, and plugins or copyable example projects exist for Bun, Nub, Vite, Next.js, esbuild, webpack, Rspack, Cloudflare Workers, and Jest.
Which databases and drivers does it work with?Postgres, MySQL and SQLite, through drivers like pg, postgres.js, mysql2, better-sqlite3, Bun.sql, Cloudflare D1 and more, including a Drizzle database over any of them.
What does Reylo actually infer beyond column types?It infers nullability from schema/joins/where clauses, cardinality (single row, row-or-null, array, or void), unions from enums or check constraints, and the shape of JSON columns and JSON Schema checks.
Why does it call itself agent-friendly?Because every type fact lives in one place — the SQL itself — an AI coding agent can't leave a stale hand-written row type behind, and the type checker will flag every caller it missed.
What does an imported query return at runtime?Calling .run() resolves to the rows shaped by the query: a unique-key match or limit 1 returns Row or null, an aggregate/one-row insert returns Row, a plain insert/update/delete returns void, and anything else returns Row[].
Creator
reylosql
Size
105.9 MB
Stars
1.6K
Age
28d
Commits · 90 Days