ilbertt/bun-sqlgen

来源: https://github.com/ilbertt/bun-sqlgen

bun-sqlgen

为 Bun 提供类型安全的 SQL，无需 ORM——原生 Bun.sql (https://bun.sh/docs/runtime/sql)， 并实时根据你的数据库模式进行检查。

给查询打上名称标签 —— sql.GetUser`...` —— 然后完全类型安全、空值安全的行数据就出现在调用处：无需 ORM、无需泛型、无需手写类型。Codegen 会依据真实的 Postgres 或 SQLite 数据库（无需 Docker）对每个查询进行规划，因此错误的列或有问题的 SQL 会在构建时失败，而非生产环境——运行速度足够快，可以在每次保存时重新运行。运行时保持 100% Bun 原生。

以 @ilbertt/bun-sqlgen (https://www.npmjs.com/package/@ilbertt/bun-sqlgen) 发布—— 其 README 是完整的指南：涵盖两种方言、可空性覆盖、事务和配置。

安装

bun add @ilbertt/bun-sqlgen

快速开始

1. 迁移文件是模式的唯一真实来源——将它们放在任意文件夹：

   -- db/migrations/0001_init.sql
   CREATE TABLE users (
     id           bigint PRIMARY KEY GENERATED ALWAYS AS IDENTITY,
     email        text NOT NULL,
     display_name text
   );
   

2. 使用 withTypes 包装客户端，并为每个查询打上名称标签：

   import { withTypes } from '@ilbertt/bun-sqlgen';
   import { SQL } from 'bun';
   
   const sql = withTypes(new SQL(Bun.env.DATABASE_URL!));
   
   export async function getUser(id: number) {
     const [user] = await sql.GetUser`
       SELECT id, email, display_name FROM users WHERE id = ${id}
     `;
     return user; // 类型为 { id: string; email: string; display_name: string | null }
   }
   

3. 生成类型：

   bun bun-sqlgen generate 'src/**/*.ts' --migrations db/migrations
   

   这会生成 src/queries.gen.d.ts——请提交该文件。有了它之后，user.emial 会导致编译错误，user.display_name.length 会被标记为可能为空，所有检查都由普通的 tsc 完成。

示例

可运行的项目位于 examples/ 文件夹中。

贡献

开发环境和约定见 CONTRIBUTING.md。