Knex.js Cheatsheet - Knex SQL Query Builder Reference
Knex.js SQL 查询构建器必备 API 都在这里了，从增删改查到事务管理，按功能分类整理，写 Node.js 数据库代码时直接复制。
Back to Databases查询数据 10
knex("users").select("*")SELECT * FROM users
knex("users").select("name", "email")查询指定列
knex("users").where("age", ">", 18)WHERE age > 18
knex("users").where({ status: "active" })WHERE status = active
knex("users").whereNull("deleted_at")WHERE deleted_at IS NULL
knex("users").orderBy("created_at", "desc")ORDER BY created_at DESC
knex("users").limit(10).offset(20)LIMIT 10 OFFSET 20 分页
knex("users").first()取第一条记录
knex("users").pluck("id")取单列值数组 [1, 2, 3]
knex("users").distinct("country")SELECT DISTINCT country
插入数据 5
knex("users").insert({ name: "John", email: "john@example.com" })插入单条
knex("users").insert([{ name: "A" }, { name: "B" }])批量插入
knex("users").insert(data).returning("id")插入并返回 ID（PG/SQLite）
knex("users").insert(data).onConflict("email").merge()冲突时更新（upsert）
knex("users").insert(data).onConflict("email").ignore()冲突时忽略
更新与删除 5
knex("users").where("id", 1).update({ name: "Jane" })更新指定记录
knex("users").where("id", 1).update({ views: knex.raw("views + 1") })自增更新
knex("users").where("id", 1).update({ deleted_at: knex.fn.now() })软删除模式
knex("users").where("id", 1).del()删除指定记录
knex("users").truncate()清空表（重置自增）
Join 关联 6
knex("users").join("posts", "users.id", "posts.user_id")INNER JOIN
knex("users").leftJoin("posts", "users.id", "posts.user_id")LEFT JOIN
knex("users").rightJoin("posts", "users.id", "posts.user_id")RIGHT JOIN
knex("users").fullOuterJoin("posts", "users.id", "posts.user_id")FULL OUTER JOIN
knex("users").crossJoin("posts")CROSS JOIN 笛卡尔积
knex("users").join("posts", function() { this.on("users.id", "=", "posts.user_id").andOn("users.active", "=", knex.raw("?", [1])) })多条件 JOIN
聚合与分组 8
knex("users").count("id as total")COUNT(id) AS total
knex("users").count("* as total").first()取总记录数
knex("orders").sum("amount")SUM(amount)
knex("users").max("age")MAX(age)
knex("users").min("age")MIN(age)
knex("orders").avg("amount")AVG(amount)
knex("users").groupBy("status")GROUP BY status
knex("users").groupBy("status").having(knex.raw("count(*) > ?", [5]))HAVING count > 5
事务 4
knex.transaction(async (trx) => { await trx("users").insert(data) })自动提交/回滚事务
const trx = await knex.transaction(); await trx.commit() / trx.rollback()手动控制事务
const sp = await trx.savepoint(async (sp) => { /* ... */ })保存点（部分回滚）
await knex.transaction(cb, { isolationLevel: "read committed" })设置事务隔离级别
Schema 构建 7
knex.schema.createTable("users", (t) => { t.increments("id"); t.string("name") })创建表
knex.schema.dropTableIfExists("users")删除表（如存在）
knex.schema.alterTable("users", (t) => { t.string("email") })修改表结构
t.integer("age").unsigned().notNullable().defaultTo(0)列约束链式调用
t.timestamps(true, true)添加 created_at/updated_at
knex.schema.table("users", (t) => { t.index(["name", "status"]) })创建复合索引
knex.schema.table("users", (t) => { t.unique("email") })添加唯一约束
原始查询与调试 5
knex.raw("SELECT * FROM users WHERE id = ?", [1])执行原生 SQL（参数化）
knex("users").where("active", true).debug(true)输出查询 SQL 到控制台
knex("users").where("id", 1).toSQL().toNative()查看生成的 SQL 和绑定值
knex("users").where("id", 1).toString()返回 SQL 字符串
knex("users").columnInfo()获取表结构信息
💡 Tips
- Knex 支持 PostgreSQL、MySQL、MariaDB、SQLite、MSSQL，连接时指定 client。
- 查询构建器返回 Promise，需要 await 或 .then() 才会执行。
- knex.raw("SQL", bindings) 执行原生 SQL，参数绑定可防 SQL 注入。
- Migration 用 knex.migrate.make() 创建，knex.migrate.latest() 执行迁移。
- 连接池默认启用，配置 pool: { min: 2, max: 10 } 调整大小。