# reylo (reylosql/reylo)

> 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.

- GitHub: https://github.com/reylosql/reylo
- GitHub.Locker page: https://github.locker/reylosql/reylo
- Stars: 1.6K
- Language: Rust
- License: MIT
- Last push: 2026-11-17

## Questions and answers

Written by GitHub.Locker from the README and the repository; check the README below for details.

**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[].


---

## README (checked against GitHub 2026-11-18)

Source: https://github.com/reylosql/reylo/blob/main/README.md

<h1 align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="site/public/readme-logo-dark.svg" />
    <img src="site/public/readme-logo-light.svg" width="160" alt="Reylo" />
  </picture>
</h1>

<p align="center">Import <code>.sql</code> files into your TypeScript code with full type inference</p>

<p align="center">
  <a href="https://github.com/reylosql/reylo/actions/workflows/test.yml"><img src="https://github.com/reylosql/reylo/actions/workflows/test.yml/badge.svg?branch=main" alt="test status" /></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/github/license/reylosql/reylo?style=flat" alt="License: MIT" /></a>
  <a href="https://www.npmjs.com/package/reylo"><img src="https://img.shields.io/github/v/release/reylosql/reylo?label=npm" alt="npm version" /></a>
  <a href="https://github.com/reylosql/reylo"><img src="https://img.shields.io/github/stars/reylosql/reylo" alt="GitHub stars" /></a>
</p>

<div align="center">
  <a href="https://reylo.dev">Read the docs →</a>
</div>

<br/>

<p align="center">
  <img src="site/public/readme-demo.gif" alt="An editor: hovering a query's result shows its type, which follows the SQL as the SQL changes" />
</p>

<br/>

If you have a file like this:

```sql
-- 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:

```ts
// 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](https://github.com/microsoft/typescript-go/pull/4712), introduced in TypeScript 7.1 (currently [in beta](https://devblogs.microsoft.com/typescript/announcing-typescript-7-1-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:

- 💪 **The full power of SQL** — any syntax, function or operator your database supports
- 🌵 **DRY** — no redundant hand-written types
- 🎯 **Checked against your database** — a misspelled column is a type error
- 🤖 **Agent-friendly** — DRY code is more maintainable for agents
- 🧩 **Postgres, MySQL and SQLite** — Neon, PlanetScale, Cloudflare D1, Turso and more
- 🔌 **Bring your own driver** — `pg`, postgres.js, `mysql2`, `better-sqlite3` and [more](#supported-drivers)
- ⚡ **No codegen** — no generated files, no watcher

## Setup

To install Reylo, you'll need:

- **TypeScript 7.1 (currently in beta).** The first release with content mappers.
- **Node 24 or later.**
- **A running dev database.** Postgres, MySQL 8.0.22 or later, or a SQLite file: Reylo reads your current schema from it.

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

```sh
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`:

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

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

```jsonc
// 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:

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

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

```sh
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](https://reylo.dev/#plugins), or copy its complete [example project](https://github.com/reylosql/reylo/tree/main/examples). To see the types as you type, set up [your editor](https://reylo.dev/#editors).

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

```sh
npx skills add reylosql/reylo --skill reylo
```

## Usage

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

```sql
-- get_user.sql
select id, name, email from users where id = :id::int
```

```ts
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](https://reylo.dev/#usage)). Every query Reylo runs is published on Node's tracing channel `reylo:query`, for a tracer or a logger to subscribe to ([Tracing](https://reylo.dev/#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:

- **Nulls** — a column is nullable unless its schema, a join or a `where` test rules null out.
- **Cardinality** — a match on a unique key is one row or `null`, and an aggregate is exactly one row.
- **Unions** — an enum, or a column whose check constraint lists its values, is a union of them.
- **JSON** — JSON the query builds, and a JSON column with a JSON Schema check, keep their shape.

Each has examples in [Inference](https://reylo.dev/#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:

- **Postgres** — `pg`, postgres.js, `Bun.sql`, PGlite, Neon, `pg-promise`, `slonik`, `@vercel/postgres`
- **MySQL** — `mysql2`, `mariadb`, PlanetScale, `Bun.sql`
- **SQLite** — `better-sqlite3`, `node:sqlite`, `Bun.sql`, libSQL, Turso, SQLite Wasm, Cloudflare D1 and Durable Objects, `sqlite3`, `sqlite`

## Documentation

[reylo.dev](https://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](https://reylo.dev/llms.txt). To move a Prisma project's queries to Reylo, see [Migrating from Prisma](https://reylo.dev/prisma).

## License

[MIT](LICENSE)

