用途：面向使用 Kysely + PostgreSQL 的 TypeScript 项目，提供类型安全 SQL 查询构建、迁移与常见问题处理的参考模式。Kysely 是类型安全 SQL 构建器，生成纯 SQL、无运行时 ORM 开销，编译期校验查询；它不是 ORM，不提供关系、懒加载。核心哲学是能用查询构建器表达就优先用构建器，仅在构建器不支持时退回 sql 模板标签。
主要能力：涵盖简单 CRUD、任意复杂度 JOIN、聚合与 GROUP BY、CTE、条件查询、JSONB/数组操作、动态列与表名、可复用 Expression 片段。ExpressionBuilder（eb）提供 eb.ref、eb.val、eb.lit、eb.fn、eb.case、eb.and/or、eb.exists、eb.cast 等方法。数据库类型通过 Generated、Insertable、Selectable、Updateable 辅助类型定义，可用 kysely-codegen 生成。迁移通过 kysely-ctl 管理，使用 db.schema.createTable 等。
使用方式：定义 Database 接口与表类型后，用 selectFrom、insertInto、updateTable、deleteFrom 等构建查询，并显式调用 .execute() 执行；复杂 JOIN 用回调格式，CTE 用 .with()，嵌套 JSON 用 jsonArrayFrom/jsonObjectFrom。
常见陷阱：eb.val 为参数化值（$1）用于用户输入，eb.lit 仅接受数字、布尔、null，字符串需用 sql 模板；忘记 .execute() 则查询不执行；列比较应用 .whereRef；sql 模板须显式类型参数；json 子查询中避免裸 selectAll()；DATE 列有时区问题；外键需手动建索引；CamelCasePlugin 与原生 SQL 混用会命名漂移；JSONB 插入在 sql 模板中需 JSON.stringify；连接池查询可能使用不同连接；WHERE 不缩小结果类型需 $narrowType；并行迁移需 allowUnorderedMigrations；JSON 聚合会改变运行时类型。官方文档见 kysely.dev/llms-full.txt。