Knex 查询构建

Knex 是 SQL query builder + 迁移工具，不强制 ORM 对象模型。适合「要手写 SQL 控制力、又要跨数据库迁移脚本」的团队，也是理解 Drizzle 底层思路的好参照。

学习目标

• 用 Knex 链式 API 查询与写入
• 编写并运行 migration / seed
• 将 Knex 接入 Fastify 插件生命周期

连接与查询

import knex from "knex";

const db = knex({
  client: "pg",
  connection: process.env.DATABASE_URL,
});

const rows = await db("tracks")
  .select("id", "slug", "title")
  .where({ slug: "nodejs-essentials" })
  .first();

await db("tracks").insert({ slug: "new-one", title: "New Track" });

链式 API 生成参数化 SQL，避免字符串拼接注入。

迁移

// migrations/20260101_create_tracks.js
export async function up(knex) {
  await knex.schema.createTable("tracks", (t) => {
    t.increments("id").primaryKey();
    t.string("slug", 64).notNull().unique();
    t.string("title", 255).notNull();
    t.timestamps(true, true);
  });
}

export async function down(knex) {
  await knex.schema.dropTable("tracks");
}

npx knex migrate:latest
npx knex seed:run

迁移文件 进 Git，与 postgresql-essentials 的 schema 变更纪律一致。

Knex 在生态中的位置

工具	角色
Knex	Builder + 迁移，偏 SQL
Drizzle	TS 类型 + kit 迁移
Sequelize	全功能 ORM 模型

已有 Knex 项目可 渐进 迁 Drizzle；新绿field API 更常选 Drizzle + Postgres。

练习

• 创建 tracks 迁移并在本地 migrate:latest
• 写 seed 插入 3 条 mock track
• Fastify 路由 onClose 钩子里 destroy() 连接池

小结

Knex = 可控 SQL + 正规迁移。 下一课 Sequelize：经典 ORM 与关联模型。