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 允许你直接在 TypeScript 代码中导入 .sql 文件,并自动获得查询结果行和参数的完整类型推断,无需代码生成步骤。
这是 ORM 还是只是一个类型层?它是一个自带驱动的类型层,而不是 ORM:你编写原生 SQL,并仍需传入自己的数据库客户端(如 pg、mysql2、better-sqlite3 等)来执行查询,Reylo 只负责类型检查和类型标注。
怎样在项目中把它跑起来?安装 Reylo,在 tsconfig.json 中为 .sql 文件添加它并指定其项目文件(.reylo.yaml 或 .reylo.yml),然后使用 --runExternalCode 标志进行类型检查,并将 DATABASE_URL 指向你的开发数据库。
我需要特定版本的 TypeScript 或实际运行的数据库吗?两者都需要:Reylo 要求 TypeScript 7.1(目前处于测试版,是首个支持内容映射器的版本)、Node 24 或更高版本,以及一个正在运行的开发用 Postgres、MySQL 8.0.22+ 或 SQLite 数据库,用于读取数据库结构。
现在能否在 TypeScript 稳定版上使用它?基本不行。Reylo 依赖内容映射器,而这一功能只存在于 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 实际还能推断出什么?它能根据结构、连接和 where 子句推断可空性,推断基数(单行、单行或空、数组,或无返回值),根据枚举或检查约束推断联合类型,以及 JSON 列的结构和 JSON Schema 检查。
为什么它称自己对 AI 代理友好?因为所有类型信息都集中在一处——SQL 本身,因此 AI 编码代理不会留下过时的手写行类型,而且类型检查器会标记出它遗漏的每一个调用方。
导入的查询在运行时返回什么?调用 .run() 后返回的是按查询结构塑形的行:唯一键匹配或 limit 1 返回 Row 或 null,聚合或单行插入返回 Row,普通的插入、更新、删除返回 void,其他情况返回 Row[]。
作者
reylosql
大小
105.9 MB
星标
1.6K
时长
28天
提交 · 90 天