Knex.js 版本升级指南与技术要点解析

Knex.js 版本升级指南与技术要点解析

knex knex: 是一个基于 Node.js 的开源 SQL 查询构建器和迁移工具，支持多种数据库。适合开发者使用 Knex 进行数据库查询和迁移等相关任务。 项目地址: https://gitcode.com/gh_mirrors/kn/knex

前言

Knex.js 是一个强大的 SQL 查询构建器，广泛应用于 Node.js 项目中。随着项目的发展，Knex.js 经历了多次重大版本更新，每个版本都可能引入破坏性变更。本文将从技术角度深入解析各版本的升级要点，帮助开发者顺利完成迁移。

升级到 2.0.0+ 版本

SQLite 驱动变更

2.0.0 版本最重要的变化是 SQLite 驱动的切换。由于 sqlite3 项目重新恢复维护，Knex.js 决定从 @vscode/sqlite3 切换回原生的 sqlite3 驱动。

操作建议：

• 在 package.json 中将 @vscode/sqlite3 依赖替换为 sqlite3
• 重新安装依赖确保驱动正常工作

升级到 1.0.0+ 版本

环境要求变更

1.0.0 版本标志着 Knex.js 对 Node.js 版本要求的重大调整：

• 最低 Node.js 版本要求提升至 12.x
• 不再支持 Node.js 10 及以下版本

SQLite 驱动反向变更

有趣的是，1.0.0 版本与 2.0.0 版本的驱动变更方向相反：

• 需要将 sqlite3 替换为 @vscode/sqlite3
• 这一变更反映了开源项目维护状态的变化

返回值格式统一

RETURNING 操作现在统一返回包含列名的对象，而不是原始值。这一变更提高了返回值的一致性。

迁移器返回值变化

迁移器现在返回迁移列表对象，而非简单的数组。这为元数据提供了更丰富的结构。

升级到 0.95.0+ 版本

TypeScript 类型系统重构

0.95.0 版本对 TypeScript 类型系统进行了重大重构，这是最需要开发者关注的变更。

导入方式变更

旧版导入方式：

import knex from 'knex';

新版导入方式：

import { knex, Knex } from 'knex';

类型命名空间调整

所有核心类型现在都位于 Knex 命名空间下：

// 旧版
import { QueryBuilder } from 'knex';

// 新版
import { Knex } from 'knex';
const qb: Knex.QueryBuilder = knex('table').select('*');

查询构建器扩展方式

扩展 QueryBuilder 的语法发生了变化：

// 旧版
declare module 'knex' {
  interface QueryBuilder {
    paginate<TResult = any[]>(params: IPaginateParams): KnexQB<any, IWithPagination<TResult>>;
  }
}

// 新版
declare module 'knex' {
  namespace Knex {
    interface QueryBuilder {
      paginate<TResult = any[]>(params: IPaginateParams): KnexQB<any, IWithPagination<TResult>>;
    }
  }
}

MSSQL 驱动重构

MSSQL 驱动进行了彻底重写，解决了连接池、错误处理和性能方面的诸多问题：

• 使用 tedious 直接替代 mssql
• 需要在依赖中将 mssql 替换为 tedious

事务回滚行为变更

事务回滚默认不再触发 Promise 拒绝。如需保留旧行为，需显式配置：

await knex.transaction(
  async (trx) => {
    // 事务逻辑
  },
  { doNotRejectOnRollback: false }
);

升级到 0.21.0+ 版本

环境要求

• 最低 Node.js 版本要求提升至 10.x
• 不再支持 Node.js 8 及以下版本

升级到 0.19.0+ 版本

连接池配置强化

• 未知的连接池配置属性现在会抛出错误
• 移除了 beforeDestroy 配置选项，建议使用 tarn.js 事件处理器替代

升级到 0.18.0+ 版本

Promise 实现变更

• 从 Bluebird Promise 切换为原生 Promise
• 移除了 Knex.Promise
• 迁移和种子文件现在接收原生 Promise

TypeScript 配置要求

确保 tsconfig.json 中包含 'es6' 库：

{
  "compilerOptions": {
    "lib": ["es6"]
  }
}

升级到 0.16.0+ 版本

数据库版本要求

• MSSQL: 最低支持版本提升至 2008

时间类型方法变更

PostgreSQL 和 MySQL 中，建议使用选项对象替代参数选项：

// 旧版
table.timestamp('created_at', true);

// 新版推荐
table.timestamp('created_at', { useTz: true });

升级到 0.15.0+ 版本

环境要求

• 最低 Node.js 版本要求提升至 6.x

MariaDB 支持变更

• 移除了专门的 mariadb 方言
• 建议使用 "mysql" 或 "mysql2" 方言替代

迁移最佳实践

1. 逐步升级：不要一次性跨越多个主要版本升级
2. 充分测试：在开发环境充分测试后再部署到生产环境
3. 查看变更日志：仔细阅读目标版本的完整变更日志
4. 备份数据：执行数据库迁移前确保有完整备份
5. 考虑兼容层：对于大型项目，可考虑实现兼容层逐步迁移

结语

Knex.js 的版本升级反映了现代 JavaScript 生态系统的演进趋势。理解这些变更背后的技术考量，有助于开发者做出更明智的架构决策。建议开发团队定期评估升级计划，以保持技术栈的现代性和安全性。

knex knex: 是一个基于 Node.js 的开源 SQL 查询构建器和迁移工具，支持多种数据库。适合开发者使用 Knex 进行数据库查询和迁移等相关任务。 项目地址: https://gitcode.com/gh_mirrors/kn/knex