先说边界：类型安全到底安全在哪里#

“类型安全 SQL”容易让人误以为编译通过就等于查询正确。更准确的说法是：

所以，Kysely 不是 SQL 验证器，也不是运行时数据校验器。它建立的是一份由开发者维护的数据库类型契约，并让查询 API 尽量遵守这份契约。

一条查询的完整心智模型#

先定义本文后面都会复用的 schema：

import type {
  ColumnType,
  Generated,
  Insertable,
  Selectable,
  Updateable,
} from 'kysely';

type CreatedAt = ColumnType<
  Date,                      // SELECT 时驱动返回的类型
  Date | string | undefined, // INSERT 时接受的类型
  never                      // 不允许 UPDATE
>;

interface UserTable {
  id: Generated<number>;
  name: string;
  email: string;
  active: boolean;
  created_at: CreatedAt;
}

interface OrderTable {
  id: Generated<number>;
  user_id: number;
  amount: number;
  status: 'pending' | 'paid' | 'refunded';
  created_at: CreatedAt;
}

export interface Database {
  users: UserTable;
  orders: OrderTable;
}

export type User = Selectable<UserTable>;
export type NewUser = Insertable<UserTable>;
export type UserUpdate = Updateable<UserTable>;

现在构造一条聚合查询：

const query = db
  .selectFrom('users as u')
  .innerJoin('orders as o', 'o.user_id', 'u.id')
  .select((eb) => [
    'u.id',
    'u.name',
    eb.fn.sum<number>('o.amount').as('total'),
  ])
  .where('o.status', '=', 'paid')
  .where('o.created_at', '>=', new Date('2026-01-01'))
  .groupBy(['u.id', 'u.name'])
  .having((eb) => eb.fn.sum<number>('o.amount'), '>', 1000)
  .orderBy('total', 'desc')
  .limit(20);

const rows = await query.execute();
// { id: number; name: string; total: number }[]

这段代码看起来接近 SQL，是因为方法名和参数都直接对应 SQL 概念。调用顺序也可以与 SQL 的阅读顺序一致。

不过，Kysely 并不是把链式调用逐段拼成字符串。它会先保存查询结构，最后再由编译器按 SQL 语法规定的顺序输出各个子句。

如果只想看编译结果，可以不执行：

const compiled = query.compile();

compiled.sql;        // 方言对应的 SQL
compiled.parameters; // ['paid', Date, 1000, 20]
compiled.query;      // RootOperationNode
compiled.queryId;    // 供插件关联查询变换与结果变换

这已经勾勒出整条链：

flowchart TD
  A["Database 类型契约"] --> B["QueryBuilder<DB, TB, O>"]
  B --> C["OperationNode AST"]
  C --> D["Plugin.transformQuery"]
  D --> E["QueryCompiler"]
  E --> F["CompiledQuery<br/>sql + parameters + queryId"]
  F --> G["Driver / DatabaseConnection"]
  G --> H["Plugin.transformResult"]
  H --> I["O[]"]
  style A fill:#6C6D6F,color:#fff
  style F fill:#E14140,color:#fff
  style I fill:#262627,color:#fff

下面逐层拆开。

Schema：一份编译期契约#

Kysely 不要求运行时 schema DSL。传给 Kysely<Database> 的泛型就是查询类型系统的起点：Database 的 key 是表名，value 是列定义。

type Generated<S> = ColumnType<S, S | undefined, S>;

类型系统：DB、TB、O 三条状态#

SelectQueryBuilder<DB, TB, O> 是理解查询类型的关键。可以把三个泛型粗略读成：

• DB：当前查询所知道的表到行类型的映射，包含别名和 JOIN 引入的可空性变化；
• TB：当前表达式允许引用的表名集合；
• O：到目前为止累计出的 SELECT 结果类型。

它们在链式调用中以不同方式演化。

selectFrom<TE extends TableExpressionOrList<DB, never>>(
  from: TE,
): SelectFrom<DB, never, TE>

db.selectFrom('users as u')

const row = await db
  .selectFrom('users as u')
  .leftJoin('orders as o', 'o.user_id', 'u.id')
  .select(['u.id', 'o.id as order_id'])
  .executeTakeFirst();

// row: { id: number; order_id: number | null } | undefined

const result = await db
  .selectFrom('users as u')
  .select([
    'u.id',
    'u.email as login',
  ])
  .executeTakeFirstOrThrow();

// { id: number; login: string }

.select((eb) => [
  'u.id',
  eb.fn.coalesce('u.name', eb.val('anonymous')).as('display_name'),
  eb
    .case()
    .when('u.active', '=', true)
    .then('active')
    .else('inactive')
    .end()
    .as('state'),
])

const row = await db
  .selectFrom('users')
  .select('id')
  .$if(includeEmail, (qb) => qb.select('email'))
  .executeTakeFirstOrThrow();

// { id: number; email?: string }

运行时：不可变的 OperationNode AST#

链式调用在运行时不会立即生成最终 SQL。每个 builder 内部都持有一个 SelectQueryNode、InsertQueryNode、UpdateQueryNode 等根节点，方法调用通过 cloneWith... 工厂创建新节点。

例如：

db.selectFrom('users').where('id', '=', 1).selectAll()

对应的结构可以简化为：

{
  kind: 'SelectQueryNode',
  from: {
    kind: 'FromNode',
    froms: [{ kind: 'TableNode', table: { /* users */ } }],
  },
  where: {
    kind: 'WhereNode',
    where: {
      kind: 'BinaryOperationNode',
      leftOperand: { kind: 'ReferenceNode', /* id */ },
      operator: { kind: 'OperatorNode', operator: '=' },
      rightOperand: { kind: 'ValueNode', value: 1 },
    },
  },
  selections: [{ kind: 'SelectionNode', /* SelectAllNode */ }],
}

这些节点是冻结的普通对象。SelectQueryNode.cloneWithSelections、QueryNode.cloneWithWhere 等函数会复制根节点并复用未变化的子树，而不是原地修改旧 builder。

const activeUsers = db
  .selectFrom('users')
  .where('active', '=', true);

const emails = await activeUsers
  .select('email')
  .execute();

const withOrders = await activeUsers
  .innerJoin('orders', 'orders.user_id', 'users.id')
  .select(['users.id', 'orders.id as order_id'])
  .execute();

插件：在编译前改 AST，在执行后改结果#

KyselyPlugin 只有两个核心入口：

// 为突出插件协议，省略了 AbortSignal 等辅助字段。
interface KyselyPlugin {
  transformQuery(args: {
    node: RootOperationNode;
    queryId: QueryId;
  }): RootOperationNode;

  transformResult(args: {
    result: QueryResult<UnknownRow>;
    queryId: QueryId;
  }): Promise<QueryResult<UnknownRow>>;
}

执行器会按注册顺序调用 transformQuery，并要求插件返回相同 kind 的根节点；查询完成后，再调用 transformResult。

内置插件能说明这套机制的用途：

• CamelCasePlugin 把 TypeScript 侧的 camelCase 标识符转换为数据库侧的 snake_case，并把结果键转回 camelCase；
• ParseJSONResultsPlugin 为不会自动解析 JSON 的方言或驱动递归解析结果；
• DeduplicateJoinsPlugin 删除结构相同的重复 JOIN；
• HandleEmptyInListsPlugin 和 SafeNullComparisonPlugin 处理特定表达式边界。

插件能够实现审计标记、租户条件等横切逻辑，但软删除或行级权限不是“给所有 SELECT 随手加一个 WHERE”那么简单。子查询、JOIN、UPDATE、DELETE 和别名都需要一致处理。

权限隔离仍应优先依赖数据库约束或行级安全策略，插件更适合做可测试的查询变换。

编译：Visitor 把 AST 变成 SQL#

DefaultQueryCompiler 继承 OperationNodeVisitor。它遍历 AST，并按 SQL 语法规定的顺序访问 selection、FROM、JOIN、WHERE、GROUP BY、HAVING 等节点。

普通值表达式通常会进入参数数组，而不是直接拼到 SQL 中。以 PostgreSQL 为例：

const compiled = db
  .selectFrom('users')
  .select('id')
  .where('email', '=', input)
  .compile();

// compiled.sql:
// select "id" from "users" where "email" = $1
// compiled.parameters:
// [input]

CompiledQuery 在 0.29.3 中包含四个字段：

interface CompiledQuery<O = unknown> {
  readonly query: RootOperationNode;
  readonly queryId: QueryId;
  readonly sql: string;
  readonly parameters: ReadonlyArray<unknown>;
}

方言编译器只覆盖差异部分。例如 PostgreSQL 使用 $1 形式的参数占位符和双引号标识符；MySQL 使用 ? 和反引号；MSSQL 使用 @1 一类占位符，并定制 OFFSET、MERGE 等语法。

Dialect：把核心与数据库驱动隔开#

Dialect 接口由四个工厂方法组成：

interface Dialect {
  createDriver(): Driver;
  createQueryCompiler(): QueryCompiler;
  createAdapter(): DialectAdapter;
  createIntrospector(db: Kysely<any>): DatabaseIntrospector;
}

• Driver 和 DatabaseConnection 负责连接、事务、执行与流式结果；
• QueryCompiler 负责把 AST 编译成目标 SQL；
• DialectAdapter 暴露方言能力和迁移锁等差异；
• DatabaseIntrospector 读取表、列、schema 和元数据。

0.29.3 源码内置 PostgreSQL、MySQL、MSSQL、SQLite 和 PGlite 方言。Cloudflare D1、PlanetScale、Neon、libSQL 等集成来自组织或社区包，应分别检查它们的维护状态、驱动语义和版本兼容性。

这也是 Kysely 能覆盖 Node.js、Deno、Bun、Cloudflare Workers 和浏览器场景的基础：核心查询模型不绑定 Node 原生模块。

但实际能否在某个运行环境中工作，取决于所选方言和底层驱动。不能只因为核心库是 TypeScript，就假设任意数据库连接都能在 Edge 环境运行。

sql 模板：参数安全与逃生口#

Builder 不可能覆盖每个数据库扩展。Kysely 用 sql 模板把原生 SQL 作为一等表达式嵌回 AST：

import { sql } from 'kysely';

const result = await db
  .selectFrom('users')
  .select([
    'id',
    sql<string>`lower(email)`.as('normalized_email'),
  ])
  .where(sql<string>`lower(email)`, '=', input.toLowerCase())
  .execute();

普通插值会被当成值参数：

sql`select * from users where email = ${input}`

但下面几类 API 会主动离开普通参数化路径：

• sql.ref(name)、sql.table(name)、sql.id(...)：动态标识符；
• sql.lit(value)：把值作为字面量写入 SQL；
• sql.raw(text)：直接注入 SQL 文本。

这些 API 的输入都应来自静态常量或严格白名单，不能直接接收用户输入。sql<T> 中的 T 也只是开发者给编译器的承诺，Kysely 不会解析 SQL 并验证返回类型。

执行链：execute() 到结果对象#

SelectQueryBuilderImpl.execute 的主路径很短，但背后职责分层清楚：

1. builder 调用 toOperationNode()；
2. QueryExecutor 依次执行插件的 transformQuery；
3. 方言 QueryCompiler 生成 CompiledQuery；
4. ConnectionProvider 获取数据库连接；
5. DatabaseConnection.executeQuery 把 SQL 和参数交给底层驱动；
6. 连接被释放，结果依次经过插件的 transformResult；
7. execute() 返回其中的 rows。

用序列图看更清晰：

sequenceDiagram
  participant U as 调用方
  participant B as QueryBuilder
  participant E as QueryExecutor
  participant P as Plugins
  participant C as QueryCompiler
  participant CP as ConnectionProvider
  participant D as DatabaseConnection

  U->>B: execute()
  B->>B: toOperationNode()
  B->>E: 执行 AST + queryId
  E->>P: transformQuery(node)
  P-->>E: 变换后的 RootOperationNode
  E->>C: compileQuery(node)
  C-->>E: CompiledQuery
  E->>CP: 请求连接
  CP-->>E: DatabaseConnection
  E->>D: executeQuery(sql, params)
  D-->>E: QueryResult
  E->>P: transformResult(result)
  P-->>E: 变换后的 QueryResult
  E-->>B: rows
  B-->>U: O[]

这条路径没有实体 hydrate、identity map 或变更追踪。结果默认就是驱动返回的普通对象；只有插件或驱动本身会改变其运行时形态。

Kysely 同时支持回调式事务。下面以支持 RETURNING 的方言为例：

await db.transaction().execute(async (trx) => {
  const user = await trx
    .insertInto('users')
    .values({
      name: 'Ada',
      email: 'ada@example.com',
      active: true,
    })
    .returning('id')
    .executeTakeFirstOrThrow();

  await trx
    .insertInto('orders')
    .values({
      user_id: user.id,
      amount: 100,
      status: 'pending',
    })
    .execute();
});

回调成功时提交，抛错时回滚。0.29.3 还提供 startTransaction() 控制式事务以及 savepoint API，但手动控制意味着调用方也必须负责所有提交、回滚和异常路径。

Migration：有执行器，没有 schema diff#

Kysely 内置 Migrator 和 schema builder：

import { sql, type Kysely } from 'kysely';

export async function up(db: Kysely<any>): Promise<void> {
  await db.schema
    .createTable('users')
    .addColumn('id', 'serial', (col) => col.primaryKey())
    .addColumn('email', 'text', (col) => col.notNull().unique())
    .addColumn('created_at', 'timestamptz', (col) =>
      col.defaultTo(sql`now()`).notNull()
    )
    .execute();
}

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

FileMigrationProvider 可以从目录加载迁移，Migrator 负责排序、迁移表、锁和事务。但它不会比较 Database interface 与数据库，也不会自动生成 schema diff。

还有一个容易忽略的 API 细节：migrateToLatest() 返回 MigrationResultSet，错误放在 error 字段中，而不是通过该方法直接抛出。启动脚本必须显式检查：

const { error } = await migrator.migrateToLatest();

if (error) {
  throw error;
}

工程上的真实代价#

Kysely 很薄，但“薄”不等于没有成本。

Kysely 与其他方案怎么选#

这不是“谁更高级”的排序，而是抽象边界不同。

选择 Kysely 的信号：

• 团队能直接评审 SQL 语义；
• 查询包含较多 CTE、聚合、窗口函数、复杂 JOIN 或动态筛选；
• 希望结果是普通对象，不需要实体生命周期；
• 愿意维护数据库迁移与 TypeScript schema 的一致性；
• 需要替换驱动或方言，同时尽量保留查询层。

不适合优先选择 Kysely 的信号：

• 团队主要按实体关系思考，希望声明式加载嵌套关系；
• 期待修改 schema 后自动生成并管理 migration；
• 需要官方 Studio、关系模型和完整 CRUD 工作流；
• 团队缺乏 SQL 评审能力，却希望工具隐藏数据库细节。

ORM 与 Kysely 也可以共存，但要明确事务归属、连接池、迁移真源和类型生成方向，避免两个数据层各自维护一份不一致的 schema。

总结#

Kysely 的核心不是“用链式 API 代替 SQL”，而是把一条查询拆成三个可组合的表示：

它刻意不做实体映射、关系元数据和 schema diff，把这些能力留给应用、数据库或其他工具。换来的不是“零抽象”，而是一层边界清晰、能从 TypeScript 一直追到最终 SQL 的抽象。

如果团队的心智模型是“SQL 由我负责，编译器帮我约束输入和结果”，Kysely 很合适。

真正需要记住的不是它有多少类型体操，而是这条边界：类型系统提高反馈速度，AST 保持运行时可组合，数据库仍然是语义与数据的最终裁判。

源码索引#

• Kysely 官方文档
• src/query-creator.ts：selectFrom 等查询入口
• src/query-builder/select-query-builder.ts：DB / TB / O、JOIN、$if 与执行
• src/util/column-type.ts：ColumnType、Generated 和三种对象投影
• src/parser/table-parser.ts：表名与别名的类型/运行时解析
• src/operation-node/：AST 节点与不可变 clone 工厂
• src/query-compiler/default-query-compiler.ts：visitor 编译主流程
• src/query-executor/query-executor-base.ts：插件、连接和执行链
• src/dialect/：核心方言、驱动、adapter 和 introspector
• src/raw-builder/sql.ts：sql 模板与安全边界
• src/migration/migrator.ts：迁移排序、锁和结果模型
• Kysely 类型生成文档