reylo README

README проекта с github.com/reylosql/reylo. Одним файлом markdown: 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)

Ищем в базе…

1.6K ·GitHub
Что это такое?Reylo позволяет импортировать файлы .sql прямо в код на TypeScript и получать полный вывод типов для строк результата и параметров запроса без отдельного шага генерации кода.
Это ORM или просто слой типов?Это слой типов с подключением собственного драйвера, а не ORM: вы пишете сырой SQL и передаёте свой клиент базы данных (pg, mysql2, better-sqlite3 и т. д.) для выполнения запросов, а Reylo только проверяет и типизирует их.
Как запустить это в проекте?Установите Reylo, добавьте его в tsconfig.json для файлов .sql и его файл проекта (.reylo.yaml или .reylo.yml), затем проверьте типы с флагом --runExternalCode и укажите DATABASE_URL на вашу базу для разработки.
Нужна ли конкретная версия TypeScript или работающая база данных?Да, и то и другое: Reylo требует TypeScript 7.1 (сейчас в бета-версии, первый релиз с content mappers), Node 24 или новее и запущенную базу для разработки — Postgres, MySQL 8.0.22+ или SQLite, из которой он может читать схему.
Можно ли использовать это со стабильной версией TypeScript уже сейчас?Не совсем: Reylo опирается на content mappers — функцию, которая есть только в бета-версии TypeScript 7.1, поэтому вы привязаны к предварительной версии компилятора, пока эта версия не выйдет.
С какими сборщиками и средами выполнения оно работает во время выполнения?Node работает из коробки, а для Bun, Nub, Vite, Next.js, esbuild, webpack, Rspack, Cloudflare Workers и Jest есть плагины или готовые примеры проектов для копирования.
С какими базами данных и драйверами оно работает?С Postgres, MySQL и SQLite через драйверы pg, postgres.js, mysql2, better-sqlite3, Bun.sql, Cloudflare D1 и другие, включая базу Drizzle поверх любой из них.
Что Reylo на самом деле выводит, кроме типов колонок?Он определяет допустимость NULL по схеме, join-ам и условиям where, кардинальность (одна строка, строка или null, массив или void), объединения типов из enum и check-ограничений, а также структуру JSON-колонок и проверки по JSON Schema.
Почему его называют дружелюбным к ИИ-агентам?Потому что каждый факт о типах хранится в одном месте — в самом SQL, поэтому ИИ-агент для написания кода не может оставить устаревший написанный вручную тип строки, а проверка типов покажет каждый вызов, который он пропустил.
Что возвращает импортированный запрос во время выполнения?Вызов .run() возвращает строки в форме, заданной запросом: при совпадении по уникальному ключу или limit 1 — Row или null, агрегат либо вставка одной строки — Row, обычная вставка/обновление/удаление — void, а во всех остальных случаях — Row[].
Какие есть похожие проекты?motherload, kysely, react-starter-kit, auth, TablePro, sqlc, effect-mq, drizzle-orm
Автор
reylosql
Размер
105.9 MB
Звёзды
1.6K
Возраст
28 д
Коммиты · 90 дней