Kysely 实战：TypeScript 类型安全 SQL 查询构建器，比 ORM 轻、比裸 SQL 安

在 TypeScript 数据库开发生态中，开发者长期面临一个两难困境：ORM（如 Prisma、TypeORM）提供类型安全但引入黑盒运行时和性能损耗，裸 SQL 灵活高效却丢失了类型检查。2026 年 npm 数据显示，Kysely 周下载量突破 150 万且增速超过 200%，它用一种优雅的方式解决了这个矛盾——直接在 TypeScript 类型系统中建模 SQL 语义，零运行时开销，100% 类型推导。如果你厌倦了 Prisma 的 Query Engine 黑盒，又不想在裸 SQL 中丢失类型安全，Kysely 可能是 2026 年最值得投入时间学习的数据库工具。

🔍 一、Kysely 的设计哲学：SQL 本位的类型安全

1.1 为什么需要「第三条路」？

在 Kysely 之前，TypeScript 开发者操作数据库只有两个选择：

Kysely 的核心理念是：SQL 本身就是最好的查询语言，不需要发明新的 DSL。它做的唯一一件事，就是用 TypeScript 的类型系统为你写的 SQL 做静态检查。

📌 记住： Kysely 不是 ORM，它是一个 类型安全的 SQL 查询构建器（Type-Safe SQL Query Builder）。它不抽象 SQL，不生成额外的运行时代码，最终编译出来的就是你期望的 SQL 字符串。

1.2 核心类型推导机制

Kysely 的魔法在于它的类型系统。你定义数据库 Schema 的类型接口后，所有的查询构建都会获得完整的类型推导：

// 定义数据库表的 TypeScript 类型 —— 这就是 Kysely 的 "Schema"
import { Kysely, Generated, ColumnType } from 'kysely'

interface Database {
  users: UsersTable
  posts: PostsTable
  comments: CommentsTable
}

interface UsersTable {
  // Generated 表示数据库自动生成（如自增主键、默认值）
  id: Generated<number>
  name: string
  email: string
  // ColumnType<输出类型, 输入类型, 更新类型> —— 精细控制读写类型
  created_at: ColumnType<Date, never, never>  // 只读，不可插入/更新
  updated_at: ColumnType<Date, never, Date>   // 只读插入，可更新
}

interface PostsTable {
  id: Generated<number>
  author_id: number
  title: string
  content: string
  status: 'draft' | 'published' | 'archived'  // 字符串字面量类型
  view_count: Generated<number>
  created_at: ColumnType<Date, never, never>
}

interface CommentsTable {
  id: Generated<number>
  post_id: number
  user_id: number
  body: string
  created_at: ColumnType<Date, never, never>
}

// 创建 Kysely 实例
const db = new Kysely<Database>({
  dialect: postgresDialect,
  // ...
})

一旦定义了 Database 接口，你写的每一个查询都会获得完整的类型提示。db.selectFrom('users') 会自动提示 users 表的所有列名，where('email', '=', value) 会检查 email 列的类型是否与 value 匹配。

💡 提示： ColumnType<Output, Input, Update> 是 Kysely 最强大的类型工具之一。它允许你为同一列定义不同的读/写/更新类型，这在处理 created_at（只读）、status（枚举）等场景中非常有用。

🚀 二、复杂查询实战：从基础到高级

2.1 基础 CRUD 与类型推导

Kysely 的查询 API 与 SQL 语句几乎一一对应，学习成本极低：

// ✅ 正确写法 — Kysely 的查询与 SQL 结构完全一致
// SELECT
const publishedPosts = await db
  .selectFrom('posts')
  .innerJoin('users', 'users.id', 'posts.author_id')
  .select([
    'posts.id',
    'posts.title',
    'posts.status',
    'users.name as author_name',  // 别名也会被正确推导类型
  ])
  .where('posts.status', '=', 'published')
  .where('posts.view_count', '>', 100)
  .orderBy('posts.created_at', 'desc')
  .limit(20)
  .execute()

// publishedPosts 的类型被自动推导为:
// { id: number; title: string; status: 'draft' | 'published' | 'archived'; author_name: string }[]

// INSERT
await db
  .insertInto('posts')
  .values({
    author_id: 1,
    title: 'Kysely 实战指南',
    content: '...',
    status: 'draft',
    // created_at 不需要传 —— 因为类型定义中 Input 类型是 never
  })
  .execute()

// UPDATE
await db
  .updateTable('posts')
  .set({ status: 'published' })
  .where('id', '=', 42)
  .execute()

// DELETE
await db
  .deleteFrom('posts')
  .where('status', '=', 'archived')
  .where('view_count', '<', 10)
  .execute()

2.2 子查询、CTE 与 Window Function

Kysely 真正展现实力的地方在于复杂查询。它完整支持子查询、Common Table Expressions（CTE）和 Window Function，且全程保持类型安全：

// 复杂查询：用 CTE + Window Function 计算每篇文章的评论排名
const result = await db
  // 定义 CTE（Common Table Expression）
  .with('post_stats', (qb) =>
    qb.selectFrom('posts')
      .innerJoin('comments', 'comments.post_id', 'posts.id')
      .select([
        'posts.id as post_id',
        'posts.title',
        'posts.author_id',
        db.fn.count('comments.id').as('comment_count'),
        // Window Function: 按作者统计评论排名
        db.fn.avg(db.fn.count('comments.id'))
          .over((ob) => ob.partitionBy('posts.author_id'))
          .as('avg_comments_per_author'),
      ])
      .groupBy(['posts.id', 'posts.title', 'posts.author_id'])
  )
  .selectFrom('post_stats')
  .innerJoin('users', 'users.id', 'post_stats.author_id')
  .select([
    'post_stats.title',
    'post_stats.comment_count',
    'users.name as author',
    'post_stats.avg_comments_per_author',
  ])
  .where('post_stats.comment_count', '>', 5)
  .orderBy('post_stats.comment_count', 'desc')
  .execute()

⚠️ 警告： Kysely 的 Window Function 类型推导在极端复杂的嵌套场景下可能会变慢（TypeScript 编译器需要更多时间）。如果你遇到 IDE 卡顿，可以将复杂查询拆分为多个子查询或使用 ExpressionWrapper 显式声明类型。

2.3 动态查询构建

实际项目中，查询条件往往是动态的（根据用户筛选条件拼接 WHERE）。Kysely 的 where 方法可以链式调用，条件式地添加过滤：

// 动态查询构建 —— 根据可选参数拼接查询
interface PostFilter {
  status?: 'draft' | 'published' | 'archived'
  authorId?: number
  keyword?: string
  minViews?: number
  sortBy?: 'created_at' | 'view_count' | 'comment_count'
  sortDir?: 'asc' | 'desc'
  page?: number
  pageSize?: number
}

async function searchPosts(filter: PostFilter) {
  let query = db
    .selectFrom('posts')
    .innerJoin('users', 'users.id', 'posts.author_id')
    .select([
      'posts.id',
      'posts.title',
      'posts.status',
      'posts.view_count',
      'posts.created_at',
      'users.name as author_name',
    ])

  // 动态添加条件 —— 类型安全且零运行时开销
  if (filter.status) {
    query = query.where('posts.status', '=', filter.status)
  }
  if (filter.authorId) {
    query = query.where('posts.author_id', '=', filter.authorId)
  }
  if (filter.keyword) {
    query = query.where('posts.title', 'like', `%${filter.keyword}%`)
  }
  if (filter.minViews) {
    query = query.where('posts.view_count', '>=', filter.minViews)
  }

  // 动态排序
  const sortBy = filter.sortBy ?? 'created_at'
  const sortDir = filter.sortDir ?? 'desc'
  query = query.orderBy(`posts.${sortBy}`, sortDir)

  // 分页
  const page = filter.page ?? 1
  const pageSize = Math.min(filter.pageSize ?? 20, 100) // 限制最大每页数量
  query = query.limit(pageSize).offset((page - 1) * pageSize)

  return await query.execute()
}

// 使用示例 —— 所有参数都是可选的，类型完全安全
const posts = await searchPosts({
  status: 'published',
  keyword: 'TypeScript',
  sortBy: 'view_count',
  page: 2,
})

🔧 三、Kysely vs Drizzle vs Prisma：深度对比

3.1 类型安全深度对比

三者都声称支持「类型安全」，但实现深度完全不同：

3.2 性能基准测试

在 Node.js 22 + PostgreSQL 16 环境下，执行 1000 次相同查询的基准测试结果：

⚡ 关键结论： Kysely 的性能几乎与裸 SQL 持平（仅多 20-30% 的查询构建开销），远超 Prisma。冷启动时间更是碾压级优势——Prisma 的 Rust Query Engine 初始化需要数百毫秒，而 Kysely 几乎为零。

3.3 迁移工作流对比

// Kysely 迁移系统 —— 纯 TypeScript，零外部依赖
import { Migrator, FileMigrationProvider } from 'kysely'
import * as path from 'path'

const migrator = new Migrator({
  db,
  provider: new FileMigrationProvider({
    fs: require('fs'),
    path: require('path'),
    // 迁移文件目录
    migrationFolder: path.join(__dirname, 'migrations'),
  }),
})

// 执行迁移
const { error, results } = await migrator.migrateToLatest()

// 每个迁移文件就是一个普通的 async 函数
// migrations/2026-05-31_create_posts.ts
import { Kysely, sql } from 'kysely'

export async function up(db: Kysely<any>): Promise<void> {
  await db.schema
    .createTable('posts')
    .addColumn('id', 'serial', (col) => col.primaryKey())
    .addColumn('author_id', 'integer', (col) =>
      col.references('users.id').onDelete('cascade').notNull()
    )
    .addColumn('title', 'varchar(255)', (col) => col.notNull())
    .addColumn('content', 'text', (col) => col.notNull())
    .addColumn('status', sql`post_status`, (col) => // 支持自定义类型（枚举）
      col.defaultTo('draft').notNull()
    )
    .addColumn('view_count', 'integer', (col) => col.defaultTo(0).notNull())
    .addColumn('created_at', 'timestamp', (col) =>
      col.defaultTo(sql`now()`).notNull()
    )
    .execute()
}

export async function down(db: Kysely<any>): Promise<void> {
  await db.schema.dropTable('posts').execute()
}

💡 提示： Kysely 的迁移文件就是普通的 TypeScript 文件，可以调用任何 npm 包。这比 Prisma 的声明式迁移灵活得多——你可以在迁移中执行数据转换、调用外部 API、甚至运行自定义校验逻辑。

💡 四、生产环境最佳实践

4.1 连接池与事务管理

// 生产环境 Kysely 初始化 —— 连接池 + 事务 + 错误处理
import { Kysely, PostgresDialect } from 'kysely'
import { Pool } from 'pg'

const db = new Kysely<Database>({
  dialect: new PostgresDialect({
    pool: new Pool({
      connectionString: process.env.DATABASE_URL,
      max: 20,                    // 最大连接数
      idleTimeoutMillis: 30000,   // 空闲连接超时
      connectionTimeoutMillis: 5000, // 连接超时
    }),
  }),
  // 生产环境建议开启查询日志（调试用）
  log: process.env.NODE_ENV === 'development' ? ['query', 'error'] : ['error'],
})

// 事务示例 —— 原子性操作
async function transferPost(postId: number, newAuthorId: number) {
  // Kysely 的事务 API 简洁且类型安全
  return await db.transaction().execute(async (trx) => {
    // 1. 检查目标作者是否存在
    const author = await trx
      .selectFrom('users')
      .select('id')
      .where('id', '=', newAuthorId)
      .executeTakeFirst()

    if (!author) {
      throw new Error(`Author ${newAuthorId} not found`)
    }

    // 2. 转移文章
    await trx
      .updateTable('posts')
      .set({ author_id: newAuthorId })
      .where('id', '=', postId)
      .execute()

    // 3. 记录操作日志（假设有一个 audit_logs 表）
    await trx
      .insertInto('audit_logs')
      .values({
        action: 'transfer_post',
        entity_type: 'post',
        entity_id: postId,
        metadata: JSON.stringify({ newAuthorId }),
      })
      .execute()

    return { success: true }
  })
}

4.2 类型安全的 Raw SQL 注入

当你需要执行 Kysely 查询构建器无法表达的复杂 SQL 时，sql 标签模板让你在 Raw SQL 中保持类型安全：

// 类型安全的 Raw SQL —— 用泛型声明返回类型
const stats = await sql<{ date: Date; count: number; cumulative: number }[]>`
  WITH daily AS (
    SELECT
      DATE(created_at) as date,
      COUNT(*) as count
    FROM posts
    WHERE created_at > NOW() - INTERVAL '30 days'
    GROUP BY DATE(created_at)
  )
  SELECT
    date,
    count,
    SUM(count) OVER (ORDER BY date) as cumulative
  FROM daily
  ORDER BY date
`.execute(db)

// stats.rows 的类型是 { date: Date; count: number; cumulative: number }[]

4.3 ⚠️ 常见坑点与避坑指南

⚠️ 警告： Kysely 的 sql 标签模板是防 SQL 注入的——它会自动参数化插值。但如果你用字符串拼接来构建 SQL，就会失去这个保护。永远使用 sql`...${param}` 语法，不要用 sql.raw(`...${param}`) 来处理用户输入。

🎯 五、选型建议与总结

谁应该用 Kysely？

• ✅ SQL 熟练的后端开发者：你写 SQL 很溜，但想要编译时类型检查
• ✅ 性能敏感的应用：不能接受 Prisma 的冷启动和运行时开销
• ✅ 复杂查询场景：需要子查询、CTE、Window Function 等高级 SQL 特性
• ✅ 从 Knex.js 迁移：Kysely 的 API 设计与 Knex 类似，迁移成本低
• ✅ 微服务/Serverless：Bundle 体积小，冷启动快

谁可能不适合？

• ❌ SQL 新手：Kysely 要求你理解 SQL，不会帮你「屏蔽」SQL 细节
• ❌ 需要全自动迁移的团队：Prisma 的 prisma migrate 更适合「声明式」迁移
• ❌ 需要 GraphQL 自动生成：Prisma/Nexus 的集成更成熟

⚡ 关键结论： Kysely 是 2026 年 TypeScript 数据库工具链中被严重低估的选手。它不会取代 Drizzle（Drizzle 的 Schema-first 理念有独特价值），更不会取代 Prisma（Prisma 的生态集成无可比拟），但如果你是一个写 SQL 很熟练、追求极致性能和类型安全的开发者，Kysely 可能是你的最佳选择。它的学习曲线极低——如果你会写 SQL，你就会用 Kysely。

🔗 相关工具推荐

• 🔧 Kysely 官方文档 — 完整 API 参考
• 🔧 Kysely GitHub — 开源仓库，活跃维护
• 🔧 kysely-codegen — 从数据库自动生成 TypeScript 类型
• 🔧 Drizzle ORM 实战指南 — SQL-first ORM 对比参考
• 🔧 Drizzle vs Prisma 深度对比 — ORM 选型决策参考
• 🔧 PostgreSQL 分区实战 — 大表查询优化配合 Kysely 使用