# Kysely - 类型安全的 SQL 查询生成器 ## 概述 Kysely 是一个类型安全的 TypeScript SQL 查询构建器，提供从数据库模式到查询结果的端到端类型安全。与 ORM 不同，它生成纯 SQL 并为您提供完全控制，同时保持完美的 TypeScript 推理。 **主要特点**： * 完整的类型推断（模式→查询→结果） * 零运行时开销（编译为 SQL） * 与数据库无关（PostgreSQL、MySQL、SQLite、MSSQL） * 包括迁移系统 * 插件生态系统（CTE、JSON、地理空间） * 需要时集成原始 SQL **安装**： npm 安装 kysely # 数据库驱动程序（选择一个） npm install pg # PostgreSQL npm 安装 mysql2 # MySQL npm install better-sqlite3 # SQLite ## 快速入门 ### 1\.定义数据库架构类型从 'kysely' 导入 { 生成的、可选择的、可插入的、可更新的 }； // 表格接口（所有列）接口用户表{ id: 生成<编号>; 电子邮件：字符串；名称：字符串|无效的; 创建时间：生成<日期>；更新时间：日期； } 接口PostTable { id: 生成<编号>; 用户 ID：号码；标题：字符串；内容：字符串；发布：生成；创建时间：生成<日期>； } // 数据库接口接口数据库{ 用户：用户表；帖子：帖子表； } // 类型安全的查询结果类型类型 User = Selectable; 类型 NewUser = Insertable; 类型 UserUpdate = Updateable; ### 2\.创建数据库实例从 'kysely' 导入 { Kysely, PostgresDialect }; 从'pg'导入{池}； const db = new Kysely<数据库>({ 方言：新的 PostgresDialect({ 池：新池（{ 主机：process.env.DB_HOST，数据库：process.env.DB_NAME，用户：process.env.DB_USER，密码：process.env.DB_PASSWORD，最大：10， }), }), }); ### 3\.类型安全查询 // 具有完整类型推断的 SELECT const 用户 = 等待数据库 .selectFrom('用户') .select(['id', '电子邮件', '姓名']) .where('created_at', '>', 新日期('2024-01-01')) .execute(); // 类型：数组<{ id: number;电子邮件：字符串；名称：字符串|空 }> // 带类型检查的 INSERT 常量 newUser: 新用户 = { 电子邮件：'alice@example.com', 名称：“爱丽丝”， Updated_at：新日期（）， }; 常量插入=等待数据库 .insertInto('用户') .values(新用户) .returningAll() .executeTakeFirstOrThrow(); // 类型：用户 // 更新等待数据库 .updateTable('用户') .set({ name: 'Alice Updated', Updated_at: new Date() }) .where('id', '=', 1) .execute(); // 删除等待数据库 .deleteFrom('用户') .where('电子邮件', '喜欢', '%@spam.com') .execute(); ## 高级查询模式 ### 与类型安全结合 // 内连接 const usersWithPosts = 等待数据库 .selectFrom('用户') .innerJoin('posts', 'posts.user_id', 'users.id') .选择([ '用户.id', '用户名', '帖子.标题', '帖子.内容', ]） .execute(); // 类型：数组<{ id: number;名称：字符串|无效的;标题：字符串；内容：字符串}> // 带空处理的 LEFT JOIN const usersWithOptionalPosts = 等待数据库 .selectFrom('用户') .leftJoin('posts', 'posts.user_id', 'users.id') .选择([ '用户.id', '用户.电子邮件', 'posts.title', // 类型：字符串 | null（来自 LEFT JOIN） ]） .execute(); // 多个连接 const complexQuery = 等待数据库 .selectFrom('帖子') .innerJoin('用户', '用户.id', '帖子.user_id') .leftJoin('comments', 'comments.post_id', 'posts.id') .选择([ 'posts.id 作为 postId', '帖子.标题', 'users.name 作为作者姓名', 'comments.id 为 commentId', ]） .execute(); ### 聚合和分组从 'kysely' 导入 { sql }; // 计数、平均值、总和 const stats = 等待数据库 .selectFrom('帖子') .选择([ '用户 ID', db.fn.count('id').as('post_count'), db.fn.avg('views').as('avg_views'), ]） .groupBy('user_id') .having(db.fn.count('id'), '>', 5) .execute(); // 类型：数组<{ user_id: number; post_count：数量； avg_views: 数量 }> // 使用原始 SQL 进行复杂聚合常量高级 = 等待数据库 .selectFrom('用户') .选择([ '用户.id', sql`COUNT(DISTINCT posts.id)`.as('total_posts'), sql<日期>`MAX(posts.created_at)`.as('latest_post'), ]） .leftJoin('posts', 'posts.user_id', 'users.id') .groupBy('用户.id') .execute(); ### 子查询 // 标量子查询 const usersWithPostCount = 等待数据库 .selectFrom('用户') .选择([ '用户.id', '用户名', (eb) => 埃布 .selectFrom('帖子') .select(eb.fn.count('id').as('count')) .whereRef('posts.user_id', '=', 'users.id') .as('post_count'), ]） .execute(); // EXISTS 子查询 const activeUsers = 等待数据库 .selectFrom('用户') .selectAll() .where((eb) => eb.存在（埃布 .selectFrom('帖子') .select('id') .whereRef('posts.user_id', '=', 'users.id') .where('created_at', '>', 新日期('2024-01-01')) ）） .execute(); // IN 子查询 const usersInTopTier = 等待数据库 .selectFrom('用户') .selectAll() .哪里( 'id', '在', db.selectFrom('帖子') .select('user_id') .groupBy('user_id') .having(db.fn.count('id'), '>', 100) ） .execute(); ### 通用表表达式 (CTE) //WITH 子句常量结果 = 等待数据库 .with('popular_posts', (db) => 数据库 .selectFrom('帖子') .select(['id', 'user_id', '标题']) .where('浏览次数', '>', 1000) ） .with('active_users', (db) => 数据库 .selectFrom('用户') .select(['id', '电子邮件']) .where('last_login', '>', 新日期('2024-01-01')) ） .selectFrom('popular_posts') .innerJoin('active_users', 'active_users.id', 'popular_posts.user_id') .selectAll() .execute(); // 递归CTE（组织层次结构）接口组织节点{ id：号码；名称：字符串；父 ID：数字 |无效的; 级别：数量； } const 层次结构 = 等待数据库 .withRecursive('org_tree', (db) => 数据库 .selectFrom('部门') .select(['id', 'name', 'parent_id', sql`0`.as('level')]) .where('parent_id', '是', null) .unionAll( 数据库 .selectFrom('部门') .innerJoin('org_tree', 'org_tree.id', 'departments.parent_id') .选择([ '部门.id', '部门.名称', '部门.parent_id', sql<数字>`org_tree.level + 1`.as('level'), ]））） .selectFrom('org_tree') .selectAll() .execute(); ## 从数据库生成模式 ### 使用 kysely-codegen # 安装 npm install --save-dev kysely-codegen # 从现有数据库生成类型 npx kysely-codegen --url“postgresql://user:pass@localhost:5432/mydb” 生成的输出： // 由 kysely-codegen 生成从 'kysely' 导入类型 { ColumnType, 生成 }; 导出接口数据库{ 用户：用户表；帖子：帖子表；评论：评论表； } 导出接口UsersTable { id: 生成<编号>; 电子邮件：字符串；名称：字符串|无效的; 创建时间：生成<日期>； } 导出接口PostsTable { id: 生成<编号>; 用户 ID：号码；标题：字符串；内容：字符串；发布：生成；创建时间：生成<日期>； } ### 自定义类型映射 // 将数据库类型映射到 TypeScript 类型接口自定义类型{ 时间戳：日期； jsonb：未知；数字：字符串； // 保持精度 uuid：字符串； } 接口产品表{ id: ColumnType<字符串, 字符串 |未定义，字符串>； // 选择、插入、更新类型元数据：ColumnType，字符串，字符串>； // JSON 列价格：ColumnType<数字，数字，数字|未定义>; // 数字 } ## 迁移 ### 迁移设置从 'kysely' 导入 { Kysely, Migrator, FileMigrationProvider }; 从 'fs' 导入 { Promise as fs } ；从“路径”导入*作为路径；常量迁移器 = 新迁移器({ 分贝，提供者：新的 FileMigrationProvider({ FS, 路径，迁移文件夹：path.join(__dirname, '迁移'), }), }); // 运行所有待处理的迁移异步函数 migrateToLatest() { const { 错误，结果 } = 等待 migrator.migrateToLatest(); 结果？.forEach((it) => { if (it.status === '成功') { console.log(`迁移 "${it.migrationName}" 执行成功`); } else if (it.status === '错误') { console.error(`迁移“${it.migrationName}”失败`); } }); 如果（错误）{ console.error('迁移失败：', error); 进程.退出(1); } } // 回滚上次迁移异步函数 migrateDown() { const { 错误，结果 } = 等待 migrator.migrateDown(); // 处理结果... } ### 迁移文件 // 迁移/001_create_users.ts 从 'kysely' 导入 { Kysely, sql }; 导出异步函数 up(db: Kysely): Promise { 等待数据库模式 .createTable('用户') .addColumn('id', 'serial', (col) => col.primaryKey()) .addColumn('email', 'varchar(255)', (col) => col.notNull().unique()) .addColumn('名称', 'varchar(255)') .addColumn('created_at', '时间戳', (col) => col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull() ） .execute(); 等待数据库模式 .createIndex('users_email_idx') .on('用户') .column('电子邮件') .execute(); } 导出异步函数 down(db: Kysely): Promise { 等待 db.schema.dropTable('users').execute(); } ### 复杂的迁移示例 // 添加外键导出异步函数 up(db: Kysely): Promise { 等待数据库模式 .createTable('帖子') .addColumn('id', 'serial', (col) => col.primaryKey()) .addColumn('user_id', '整数', (col) => col.references('users.id').onDelete('cascade').notNull() ） .addColumn('标题', 'varchar(500)', (col) => col.notNull()) .addColumn('内容', '文本') .execute(); } // 修改表导出异步函数 up(db: Kysely): Promise { 等待数据库模式 .alterTable('用户') .addColumn('生物', '文本') .execute(); 等待数据库模式 .alterTable('用户') .modifyColumn('电子邮件', 'varchar(320)') .execute(); } // 添加枚举列 (PostgreSQL) 导出异步函数 up(db: Kysely): Promise { 等待 sql`CREATE TYPE user_role AS ENUM ('admin', 'user', 'guest')`.execute(db); 等待数据库模式 .alterTable('用户') .addColumn('角色', sql`user_role`, (col) => col.defaultTo('用户')) .execute(); } ## 交易 ### 基本交易 // 出错时自动回滚等待 db.transaction().execute(async (trx) => { 等待交易 .insertInto('用户') .values({ 电子邮件：'alice@example.com'，名称：'Alice'，updated_at：new Date() }) .execute(); 等待交易 .insertInto('帖子') .values({ user_id: 1, title: '第一篇文章', content: '你好' }) .execute(); }); // 手动事务控制 const trx = 等待 db.transaction().execute(async (trx) => { const 用户 = 等待 trx .insertInto('用户') .values({ 电子邮件：'bob@example.com'，姓名：'鲍勃'，updated_at：new Date() }) .returningAll() .executeTakeFirstOrThrow(); const post = 等待 trx .insertInto('帖子') .值({ user_id: 用户.id, title: '鲍勃的帖子', 内容：'内容'， }) .returningAll() .executeTakeFirstOrThrow(); 返回 { 用户，帖子 }； }); ### 隔离级别从 'kysely' 导入 { IsolationLevel } ； // 读取已提交（默认）等待 db.transaction() .setIsolationLevel('读取已提交') .execute(异步(trx) => { // 交易逻辑 }); // 可串行化（最强隔离）等待 db.transaction() .setIsolationLevel('可序列化') .execute(异步(trx) => { 常量余额 = 等待 trx .selectFrom('账户') .select('余额') .where('id', '=', accountId) .executeTakeFirstOrThrow(); 等待交易 .updateTable('账户') .set({ 余额: 余额. 余额 - 金额 }) .where('id', '=', accountId) .execute(); }); ## 原始 SQL 集成 ### 使用 sql 模板标签从 'kysely' 导入 { sql }; // SELECT 中的原始 SQL 常量结果 = 等待数据库 .selectFrom('用户') .选择([ 'id', sql<字符串>`UPPER(名称)`.as('大写名称'), sql`EXTRACT(YEAR FROMcreated_at)`.as('year_created'), ]） .execute(); // WHERE 中的原始 SQL 常量过滤=等待数据库 .selectFrom('帖子') .selectAll() .where(sql`LOWER(标题)`, '喜欢', '%typescript%') .execute(); // 复杂的原始查询 const custom = wait sql<{ 总数：数量；平均年龄：数字 }>` 选择 COUNT(*) 总计， AVG(EXTRACT(年龄(出生日期))) 作为 avg_age 来自用户 WHERE 活动 = true `.execute(db); ### 完整原始查询 // 执行任意SQL 常量结果=等待sql` 与排名帖子 AS ( 选择 p.*, ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY Views DESC) 作为排名来自帖子 p ）从排名 <= 3 的排名帖子中选择 * `.execute(db); // 参数化原始查询 const email = 'alice@example.com'; const 用户 = 等待 sql<用户>` SELECT * FROM users WHERE email = ${email} `.execute(db); ## 插件生态系统 ### JSON 操作 (PostgreSQL) 从 'kysely/helpers/postgres' 导入 { jsonBuildObject, jsonArrayFrom }; // 构建 JSON 对象 const usersWithPosts = 等待数据库 .selectFrom('用户') .选择([ '用户.id', '用户名', jsonArrayFrom( 数据库 .selectFrom('帖子') .select(['posts.id', 'posts.title', 'posts.content']) .whereRef('posts.user_id', '=', 'users.id') ).as('帖子'), ]） .execute(); // 结果: { id: 1, name: "Alice", posts: [{ id: 1, title: "..." }] } // JSON聚合 const 嵌套 = 等待数据库 .selectFrom('用户') .选择([ '用户.id', jsonBuildObject({ name: '用户名', 电子邮件：'用户.电子邮件'， postCount: sql`(SELECT COUNT(*) FROM posts WHERE user_id = users.id)`, }).as('用户数据'), ]） .execute(); ### 分页插件从 'kysely' 导入 { SelectQueryBuilder }；函数 paginate( 查询：SelectQueryBuilder, 页码：页码，页面大小：数量）{ return query.limit(pageSize).offset((page - 1) * pageSize); } // 用法常量页=2；常量页面大小 = 20; const 用户 = 等待分页（ db.selectFrom('用户').selectAll(), 页，页面大小 ).execute(); // 带有总计数异步函数 paginateWithCount( 查询：SelectQueryBuilder, 页码：页码，页面大小：数量）{ const [items, { count }] = wait Promise.all([ query.limit(pageSize).offset((page - 1) * pageSize).execute(), query.select(db.fn.count('id').as('count')).executeTakeFirstOrThrow(), ]); 返回{ 物品，总计：计数，页，页面大小，总页数：Math.ceil(计数/页大小), }; } ### 全文搜索 (PostgreSQL) // 用于全文搜索的 GIN 索引导出异步函数 up(db: Kysely): Promise { 等待sql` 更改表帖子添加列 search_vector tsvector 始终生成为 ( to_tsvector('英语', 合并(标题, '') || ' ' || 合并(内容, '')) ) 已存储 `.execute(db); 等待sql` 使用 GIN (search_vector) 在帖子上创建索引 posts_search_idx `.execute(db); } // 全文搜索查询 const searchResults = 等待数据库 .selectFrom('帖子') .selectAll() .哪里( sql`搜索向量`, '@@', sql`to_tsquery('英语', ${query})` ） .execute(); ## 凯瑟利 vs 细雨 vs Prisma ### 功能比较特色| **凯瑟利** | **毛毛雨** | **棱镜** ---|---|---|--- **类型安全** |完整（模式→查询）|完整（模式→查询）|完整（生成的客户端） **SQL 控制** | ✅ 原始 SQL 友好 | ✅ 原始 SQL 友好 | ❌ 有限 **捆绑尺寸** | 〜50kB | 〜30kB | ~500kB+ **迁移系统** | ✅ 内置 | ✅ 内置 | ✅ 强大的 CLI **查询性能** | ✅ 普通 SQL | ✅ 普通 SQL | ❌ 较慢（抽象） **架构定义** | TypeScript 类型 | TypeScript 架构 | Prisma 架构 **需要代码生成** |可选|没有 | ✅ 必填 **ORM 功能** | ❌ 仅限查询构建器 |部分（关系）| ✅ 完整的 ORM **学习曲线** |中（SQL知识）|中等|简单（抽象 SQL） **最适合** | SQL优先的复杂查询|类型安全模式 |快速原型制作 ### 何时选择 Kysely ✅ **在以下情况下选择 Kysely：** * 您了解 SQL 并且想要完全控制 * 复杂查询（CTE、窗口函数、子查询） * 性能至关重要（无 ORM 开销） * 从原始 SQL 迁移 * 经常需要原始 SQL 转义舱口 * 使用现有数据库 * 束大小很重要（边缘函数） ❌ **在以下情况下选择毛毛雨：** * 想要声明性的 TypeScript 模式 * 需要关系查询能力 * 更喜欢带有 SQL 控制的类似 ORM 的人体工程学 * 参与新的绿地项目 ❌ **在以下情况下选择 Prisma：** * 团队不熟悉 SQL * 快速原型设计和迭代 * 需要强大的迁移工具 * 想要自动关系处理 * 更喜欢声明式模式语言 ### 从 Prisma 迁移 // 棱镜 const 用户 = 等待 prisma.user.findMany({ 其中： { createAt: { gte: new Date('2024-01-01') } }, 包括：{帖子：true}， }); // 凯瑟琳等价 const 用户 = 等待数据库 .selectFrom('用户') .选择([ '用户.id', '用户.电子邮件', jsonArrayFrom( db.selectFrom('帖子') .selectAll() .whereRef('posts.user_id', '=', 'users.id') ).as('帖子'), ]） .where('created_at', '>=', 新日期('2024-01-01')) .execute(); ## 最佳实践 1. **首先定义模式类型** \- 使用`Generate`、`Selectable`、`Insertable`、`Updateable` 2. **使用 kysely-codegen** \- 从现有数据库生成类型 3. **利用类型推断** \- 让 TypeScript 推断结果类型 4. **使用事务** \- 用于多步操作 5. **需要时使用原始 SQL** \- 不要与查询构建器对抗 6. **对大型结果进行分页** \- 使用 LIMIT/OFFSET 或基于游标 7. **索引经常查询的列** \- 性能是你的责任 8. **测试迁移** \- 向上和向下 9. **使用 CTE 提高可读性** \- 复杂的查询变得可维护 10. **连接池** \- 适当配置数据库池 ## 常见陷阱 ❌ **忘记执行查询**： // 错误 - 返回查询构建器，而不是结果 const users = db.selectFrom('users').selectAll(); // 正确 const users = wait db.selectFrom('users').selectAll().execute(); ❌ **不处理 LEFT JOIN 中的 null** ： // TypeScript 知道 LEFT JOIN 中 posts.title 可以为 null 常量结果 = 等待数据库 .selectFrom('用户') .leftJoin('posts', 'posts.user_id', 'users.id') .select(['用户名', '帖子.标题']) .execute(); // posts.title 类型: string |空 ❌ **缺少为自动增量列生成的**： // 错误 - TypeScript 在 INSERT 中需要“id” 接口用户表{ id：号码； // 坏的！ } // 正确接口用户表{ id: 生成<编号>; // INSERT 不需要 id } ## 资源 * **文档**： * **GitHub**： * **不和谐**： * **kysely-codegen** ： * **游乐场** : ## 相关技能使用 Kysely 时，请考虑以下补充技能： * **typescript-core** ：TypeScript 类型系统、高级模式和 tsconfig 优化 * **数据库迁移** ：生产数据库的安全模式演化模式 * **Node.js 后端** ：服务器设置、连接池和数据库配置 ### 快速 TypeScript 类型系统参考（内联以供独立使用） // Kysely 利用高级 TypeScript 功能从 'kysely' 导入 { Kysely, 生成的, ColumnType }; // 具有生成类型的数据库接口接口数据库{ 用户：{ id: 生成<编号>; // 由数据库自动生成电子邮件：字符串；创建时间：ColumnType<日期，字符串|未定义，从不>； // ColumnType<选择类型、插入类型、更新类型> }; } // 查询中的类型推断 const db = new Kysely({ /* 配置 */ }); // 完全类型安全 - TypeScript 知道返回类型 const 用户 = 等待数据库 .selectFrom('用户') .select(['id', '电子邮件']) .where('created_at', '>', 新日期('2025-01-01')) .execute(); // 类型：数组<{ id: number;电子邮件：字符串}> // 动态查询的条件类型类型 SelectFields = { [K in keyof T]: T[K] extends ColumnType ？ S：T[K]； }; ### 快速数据库迁移模式（内联供独立使用） **安全迁移原则：** 1. **向后兼容** \- 新代码适用于旧模式 2. **可逆** \- 如果需要可以回滚迁移 3. **零停机** \-无服务中断 4. **增量** \- 小改动，而不是大爆炸重写 **Kysely 迁移示例：** // 迁移/001_add_full_name.ts 从 'kysely' 导入 { Kysely, sql }; 导出异步函数 up(db: Kysely): Promise { // 第 1 阶段：添加新列（最初可为空）等待数据库模式 .alterTable('用户') .addColumn('全名', 'varchar(255)') .execute(); // 第2阶段：回填数据等待数据库 .updateTable('用户') .设置({ 全名：sql`concat(名字，''，姓氏)` }) .execute(); // 第 3 阶段：设为必需（建议单独迁移） // 等待 db.schema // .alterTable('用户') // .alterColumn('full_name', (col) => col.setNotNull()) // .execute(); } 导出异步函数 down(db: Kysely): Promise { 等待数据库模式 .alterTable('用户') .dropColumn('全名') .execute(); } **常见安全迁移：** // 添加索引（PostgreSQL 并发）等待数据库模式 .createIndex('idx_users_email') .on('用户') .column('电子邮件') .execute(); // 重命名列（多阶段方法） // 第 1 阶段：添加新列等待数据库模式 .alterTable('用户') .addColumn('email_address', 'varchar(255)') .execute(); // 第2阶段：复制数据等待数据库 .updateTable('用户') .set({ email_address: sql`email` }) .execute(); // 第 3 阶段：删除旧列（部署后） // 等待 db.schema // .alterTable('用户') // .dropColumn('电子邮件') // .execute(); // 更改列类型（添加新列、迁移列、删除旧列）等待数据库模式 .alterTable('产品') .addColumn('price_cents', '整数') .execute(); 等待数据库 .updateTable('产品') .set({price_cents: sql`cast(价格 * 100 作为整数)` }) .execute(); **运行迁移：** // 迁移.ts 从 'kysely' 导入 { Kysely, Migrator, FileMigrationProvider }; 从 'fs' 导入 { Promise as fs } ；从“路径”导入路径；常量迁移器 = 新迁移器({ 分贝，提供者：新的 FileMigrationProvider({ FS, 路径，迁移文件夹：path.join(__dirname, '迁移'), }), }); // 迁移到最新的 const { 错误，结果 } = 等待 migrator.migrateToLatest(); // 向上/向下移动等待 migrator.migrateUp(); 等待 migrator.migrateDown(); // 列出待处理的迁移 const 迁移 = 等待 migrator.getMigrations(); [如果一起部署，则各自的技能中可以使用完整的 TypeScript 模式和迁移工作流程] ## 总结 * **Kysely** 是类型安全的 SQL 查询生成器，而不是 ORM * **从模式定义到查询结果的完整类型推断** * **零运行时开销** \- 编译为纯 SQL * **迁移系统** 包含向上/向下支持 * **当查询构建器不够时，原始 SQL 集成** * **插件生态系统**，用于 JSON、分页、全文搜索 * **最适合**了解 SQL 并希望类型安全的开发人员 * **替代** Prisma（完整的 ORM）和 Drizzle（架构优先） * **非常适合**复杂查询、现有数据库、性能关键型应用程序

询问

包含技能