跳至主内容区
非官方测试版翻译

本页面由 PageTurner AI 翻译（测试版）。未经项目官方认可。 发现错误？ 报告问题 →

发布说明 1.0

TypeORM 1.0 是一个重大版本更新，移除了长期废弃的 API，更新了平台要求，并整合了 0.3.x 周期中积累的数十项错误修复与新功能。

破坏性变更​

详细升级指南请参阅升级指南。

平台要求​

  • 必须使用 Node.js 20+ — 不再支持 Node.js 16 和 18，最低 JavaScript 目标版本变更为 ES2023 (#11382 by @alumni)

  • 移除 Buffer polyfill — 非 Node 平台现使用 Uint8Array 处理二进制数据；Node.js 的 Buffer（继承自 Uint8Array）仍保持原有行为 (#11935 by @pujux)

  • 替换全局文件库 — glob 已被 tinyglobby 替代，同时移除了 rimraf，有效减少依赖项数量 (#11699 by @alumni)

  • 哈希功能迁移至原生 crypto — 弃用 sha.js 和 uuid 包，改用原生 crypto 模块及 crypto.randomUUID() 实现 (#11864 by @G0maa, #11769 by @mag123c)

驱动程序变更​

  • MySQL / MariaDB：弃用 mysql 包 — 仅支持 mysql2，同时移除 connectorPackage 配置项 (#11766 by @pkuczynski)

  • MySQL：legacySpatialSupport 默认值改为 false — 现默认使用标准 ST_GeomFromText/ST_AsText 函数 (#12083 by @pkuczynski)

  • MySQL：移除 width 和 zerofill 列选项 — 这些选项已在 MySQL 8.0.17 废弃并于 MySQL 8.4 正式移除 (#12084 by @pkuczynski)

  • SQLite：弃用 sqlite3，默认采用 better-sqlite3 — 不再支持 sqlite3 包，同时移除 flags 和 busyTimeout 配置项 (#11836 by @pkuczynski)

  • MongoDB：必须使用驱动 v7+ — 不再支持 MongoDB Node.js 驱动 v5/v6；移除 stats() 方法；清理废弃连接选项；停止导出内部类型 (#12208 by @naorpeled, #12179 by @pkuczynski, #12120 by @pkuczynski, #12037 by @alumni)

  • MS SQL Server: domain 连接选项已移除 — 请改用 authentication 并指定 NTLM 类型 (#12135 by @pkuczynski)

  • MS SQL Server：options.isolation 重命名为 options.isolationLevel — 值格式从 READ_COMMITTED 改为 READ COMMITTED 以匹配 IsolationLevel 类型；新增 SNAPSHOT 隔离级别 (#12231 by @Cprakhar)

  • SAP HANA: 废弃的连接别名已移除 — hanaClientDriver、pool.max、pool.requestTimeout、pool.idleTimeout 等选项已移除，请使用其现代等效选项 (#12080 by @gioboa)

  • Expo: 旧版驱动已移除 — 旧版 Expo SQLite 驱动已被移除；请使用 Expo SDK v52+ 配合现代异步 API (#11860 by @G0maa)

  • Redis: 旧版客户端支持已移除 — 查询结果缓存功能仅支持现代 Redis 客户端 (v4+) (#12057 by @G0maa)

已移除的 API​

  • Connection 和 ConnectionOptions 已移除 — 请改用 DataSource 和 DataSourceOptions (#12022 by @alumni)

  • .connection 属性重命名为 .dataSource — Driver、QueryRunner、EntityManager、QueryBuilder、EntityMetadata 及所有 *Event 订阅接口中的 connection 属性已更名为 dataSource；提供向后兼容的废弃 getter 作为过渡 (#12244, #12245, #12246, #12249 by @pkuczynski)

  • ConnectionManager 及全局便捷函数已移除 — createConnection、getConnection、getManager、getRepository、createQueryBuilder 等全局方法已被移除 (#12098 by @michaelbromley)

  • getMongoRepository 和 getMongoManager 全局方法已移除 — 请改用 dataSource.getMongoRepository() 和 dataSource.mongoManager (#12099 by @pkuczynski)

  • DataSource.name 已移除 — 命名连接在 v0.3 已废弃；ConnectionOptionsReader.all() 已重命名为 get() (#12136 by @pkuczynski)

  • TYPEORM_* 环境变量支持已移除 — ConnectionOptionsEnvReader、ormconfig.env 和 dotenv 自动加载功能已被移除 (#12134 by @pkuczynski)

  • findByIds 已移除 — 请改用 findBy 配合 In 操作符 (#12114 by @pkuczynski)

  • 移除 findOneById — 请改用 findOneBy (#12198 by @pkuczynski)

  • Repository.exist() 已移除 — 请改用 Repository.exists() (#12131 by @pkuczynski)

  • AbstractRepository、@EntityRepository 和 getCustomRepository 已移除 — 请改用 Repository.extend() (#12096 by @pkuczynski)

  • @RelationCount 装饰器已移除 — 请改用 @VirtualColumn 配合子查询 (#12181 by @pkuczynski)

  • 移除了 IoC 容器系统 — useContainer()、getFromContainer() 及相关类型已移除 (#12180 by @pkuczynski)

  • 移除了 readonly 列选项 — 请改用 update: false (#12132 by @pkuczynski)

  • 移除了 ColumnNumericOptions 中的 unsigned 属性 — 仅影响 decimal/float 类型；整型的 unsigned 保持不变 (#12133 by @pkuczynski)

  • QueryBuilder：移除了 onConflict()、已弃用的 orUpdate() 重载及 setNativeParameters() — 请改用 orIgnore()/orUpdate() 数组签名和 setParameters() (#12090 by @pkuczynski)

  • QueryBuilder：移除 printSql() — 该功能已冗余，因为所有执行查询均已通过配置的日志记录器输出；请改用 getSql() 或 getQueryAndParameters() 检查 SQL (#12151 by @naorpeled, #12220 by @pkuczynski)

  • QueryBuilder：移除了 WhereExpression 类型别名 — 请改用 WhereExpressionBuilder (#12097 by @pkuczynski)

  • QueryBuilder：移除了 replacePropertyNames() — 该函数实际为空操作 (#12178 by @pkuczynski)

  • 移除 join 查询选项 — LEFT JOIN 请使用 relations，其他连接类型请使用 QueryBuilder (#12188 by @pkuczynski)

  • 移除字符串形式的 select — 请改用对象语法 select: { id: true } 替代 select: ["id"] (#12214 by @pkuczynski)

  • 移除字符串形式的 relations — 请改用对象语法 relations: { profile: true } 替代 relations: ["profile"] (#12215 by @pkuczynski)

  • 移除了已弃用的锁模式 — pessimistic_partial_write 和 pessimistic_write_or_fail 已被带 onLocked 选项的 pessimistic_write 替代 (#12093 by @pkuczynski)

  • 移除了 QueryRunner.loadedTables 和 loadedViews — 请改用 getTables() 和 getViews() (#12183 by @pkuczynski)

  • 移除了 MigrationExecutor.getAllMigrations() — 请改用 getPendingMigrations()、getExecutedMigrations() 或 dataSource.migrations (#12142 by @pkuczynski)

  • 移除了 EntityMetadata.createPropertyPath() 静态方法 — 此为内部工具函数，无公开替代方案 (#12141 by @pkuczynski)

  • 移除了驱动程序与查询构建器中的内部 nativeParameters 管道 (#12104 by @pkuczynski)

  • 移除了 Broadcaster 中的内部 broadcastLoadEventsForAll() 方法 (#12137 by @pkuczynski)

  • 移除了内部 DriverUtils.buildColumnAlias() — 请改用 buildAlias() (#12138 by @pkuczynski)

  • 移除 RdbmsSchemaBuilder.renameTables() — 该空方法从未被调用过 (#12284 by @naorpeled)

行为变更​

  • 非空关系现使用 INNER JOIN — 标记为 nullable: false 的 ManyToOne 和所属端 OneToOne 关系现使用 INNER JOIN 替代 LEFT JOIN，可能导致含孤立外键的行被排除 (#12064 by @pkuczynski)

  • invalidWhereValuesBehavior 现在默认设置为 throw — 在 where 条件中传递 null 或 undefined 现在会抛出错误，而不是静默忽略该属性；需使用 IsNull() 进行 null 匹配 (#11710 by @naorpeled)

  • invalidWhereValuesBehavior 仅作用于高层级 API — QueryBuilder 的 .where(), .andWhere(), .orWhere() 方法不再受此设置影响 (#11878 by @naorpeled)

新特性​

Query Builder​

  • INSERT INTO ... SELECT FROM ... — InsertQueryBuilder 新增 valuesFromSelect() 方法，用于数据迁移和转换查询 (#11896 by @Cprakhar)

  • update/upsert 支持 returning 选项 — repository 和 entity manager 的 update() 与 upsert() 方法现支持在支持 RETURNING 子句的数据库中使用 returning 选项 (#11782 by @naorpeled)

  • 所有 drop 方法新增 ifExists 参数 — dropColumn, dropIndex, dropPrimaryKey, dropForeignKey, dropUniqueConstraint, dropCheckConstraint, dropExclusionConstraint 及其复数形式现在都支持 ifExists 标志 (#12121 by @pkuczynski)

  • QueryRunner 显式资源管理 — 支持 await using 语法 (TypeScript 5.2+) 实现自动资源清理 (#11701 by @alumni)

数据库驱动​

  • PostgreSQL: 枚举变更支持 ADD VALUE — 添加新枚举值时，TypeORM 现在会优先使用更简洁的 ALTER TYPE ... ADD VALUE 语法，而非原有的重命名-创建-迁移-删除四步流程 (#10956 by @janzipek)

  • PostgreSQL: 支持额外扩展 — 新增 installExtensions 选项可在连接建立时自动安装额外 PostgreSQL 扩展 (#11888 by @Cprakhar)

  • PostgreSQL: 部分索引支持 — 新增对 PostgreSQL 部分索引的支持 (#11318 by @freePixel)

  • SAP HANA: SELECT 语句支持锁机制 — SAP HANA 查询现在支持 FOR UPDATE 及其他锁模式 (#11996 by @alumni)

  • SAP HANA: 表注释支持 — @Entity({ comment: "..." }) 现可在 SAP HANA 中正常生效 (#11939 by @Cprakhar)

  • SAP HANA: 连接池超时控制 — 新增 maxWaitTimeoutIfPoolExhausted 连接池选项 (#11868 by @alumni)

  • SQLite: jsonb 列类型 — SQLite 现在支持 jsonb 列类型 (#11933 by @Cprakhar)

  • React Native: 加密密钥 — 新增选项可为 React Native SQLite 数据库传递加密密钥 (#11736 by @HtSpChakradharCholleti)

持久化与 Upsert​

  • clear() 中的级联截断 — Repository.clear() 和 EntityManager.clear() 现在接受 { cascade: true } 参数，可在 PostgreSQL、CockroachDB 和 Oracle 上执行 TRUNCATE ... CASCADE (#11866 by @Cprakhar)

  • 改进 increment/decrement 类型推断 — 条件参数现在使用实体感知类型替代 any (#11294 by @OSA413)

列类型与装饰器​

  • @Exclusion 支持可延迟约束 — 功能与 @Unique 和 @Index 现有的可延迟约束支持保持一致 (#11802 by @oGAD31)

其他​

  • v1迁移的自动化代码修改工具 — 新的 @typeorm/codemod 包可自动处理多数破坏性变更：运行 npx @typeorm/codemod v1 src/ 即可更新导入语句、重命名API、修复查询选项语法等 (#12233 by @pkuczynski)

  • 改进 ormconfig 错误处理 — 加载失败时现在会记录警告而非静默失败 (#11871 by @Cprakhar)

错误修复​

查询生成​

  • orderBy 中正确转义列别名 — 防止列别名与保留字冲突导致的 SQL 错误 (#12027 by @Cprakhar)

  • addOrderBy 解析数据库列名 — 使用数据库列名（例如 created_at）替代属性名现在可正确生效 (#11904 by @smith-xyz)

  • 子查询列排序解析 — 修复按子查询列排序时出现的 "Cannot get metadata for given alias" 错误 (#11343 by @trannhan0810)

  • 保留 select 列顺序 — getQuery()/getSql() 现在按 select() 和 addSelect() 添加顺序返回列 (#11902 by @Cprakhar)

  • 修复 .update() 查询生成 — 修正使用 QueryBuilder .update() 时错误的 SQL 生成 (#11993 by @gioboa)

  • 带表别名的 Upsert SQL 生成 — 修复表继承和自定义模式场景下 upsert 查询的列引用错误 (#11915 by @Cprakhar)

  • 连接查询的分页修复 — 修复使用 skip/take 分页时连接查询返回错误结果的问题 (#11987 by @gioboa)

  • 方括号内的 JOIN 属性 — 修复了条件包含括号时的 JOIN 解析问题 (#11218 by @balkrushna)

  • 禁用聚合函数的全局 ORDER BY — repo.max()、repo.min() 等方法不再生成包含 ORDER BY 子句的无效 SQL (#11925 by @Cprakhar)

  • 分页子查询包含关联实体主键 — 使用 leftJoin 配合 skip/take 现在能正确加载关联实体 (#11669 by @mag123c)

  • 驼峰命名法的别名缩写 — shorten 方法现在能正确处理 camelCase_aliases 格式 (#11283 by @OSA413)

关联关系与预加载​

  • 现在会删除具有非空外键的孤立的"一对多"子项 — 当保存具有级联的一对多关系并替换子项时，具有非空外键的孤立行现会被删除（而非因约束冲突失败）；可为空外键的行仍保持原有置空行为 (#11982 by @naorpeled)

  • 急加载关系现支持 relationLoadStrategy: "query" 策略 — 当设置为"query"策略时，急加载关系将通过独立查询实现（而非始终使用JOIN） (#11326 by @SharkSharp, #12256 by @pkuczynski)

  • 自引用关系别名冲突 — 使用 relationLoadStrategy: "query" 的自引用关系不再因别名冲突生成错误 SQL (#11066 by @campmarc)

  • 预加载关系不再重复 JOIN — 在 relations 中显式指定预加载关系不再导致重复 JOIN (#11991 by @veeceey)

  • 保存带预加载关系的实体 — 修复实体包含预加载关系时保存失败的问题 (#11975 by @gioboa)

  • select: false 字段不再返回 — 标记为 select: false 的字段现在能正确从查询结果中排除 (#11944 by @gioboa)

  • 使用 joinMapOne 方法的子查询 — 修复使用 JOIN 映射方法时的错误行为 (#11943 by @gioboa)

  • 嵌套嵌入实体的关联 ID — 修复映射嵌入实体内关联 ID 时的 TypeError: Cannot set properties of undefined 错误 (#11942 by @Cprakhar)

  • RelationIdLoader 别名处理 — 使用 DriverUtils.getAlias 防止因数据库标识符长度限制导致的别名截断 (#11228 by @te1)

  • createPropertyPath 中的 *-to-many — 移除了阻止特定关系配置的错误处理逻辑 (#11119 by @ThbltLmr)

持久化​

  • 带 update: false 或 generatedType 的 Upsert — upsert 现在能正确处理不应更新的字段 (#12030 by @gioboa)

  • 值转换器应用于 FindOperator — ApplyValueTransformers 现在能正确转换 In、Between 等 FindOperator 实例内部的值 (#11172 by @ZimGil)

  • 软删除不再更新已软删除的行 — softDelete 和 softRemove 现在会跳过已软删除的行 (#10705 by @hassanmehdi98)

  • 实体合并正确处理 null 值 — 合并到实体时不再静默丢弃 null 属性值 (#11154 by @knoid)

  • Map/对象比较 — 修复了 Map 和普通对象列值变化检测不正确的问题 (#10990 by @mgohin)

  • 日期转换器变更检测 — 修复了使用日期值转换器时误报脏数据的问题 (#11963 by @gioboa)

  • 子节点 mpath 更新 — 重新设置父节点时，树实体的 mpath 现在能正确更新，即使父节点已被软删除 (#10844 by @JoseCToscano)

  • 闭包关联表模式/数据库传播 — 模式与数据库设置现能正确传播至闭包关联表 (#12110 by @pkuczynski)

  • 模式构建器中虚拟属性的处理 — 模式构建器不再尝试为虚拟属性创建列 (#11000 by @skyran1278)

  • 无名 TableForeignKey 的删除 — 删除未显式命名的外键不再失败 (#10744 by @taichunmin)

  • getPendingMigrations 不再创建迁移表 — 检查待定迁移不再产生副作用 (#11672 by @pkuczynski)

驱动特定修复​

  • PostgreSQL: timestamptz 持久化/水合 — timestamp with time zone 类型的列现在能正确持久化和水合 (#11774 by @Minishlink)

  • PostgreSQL: 几何类型重新保存 — 点/圆值在持久化时会被标准化，以避免重新保存水合对象时出现无效输入错误 (#11857 by @Cprakhar)

  • PostgreSQL/CockroachDB: 带引号的表名 — 修复了处理表名中包含特殊字符的情况 (#10993 by @iskalyakin)

  • PostgreSQL: 顺序查询执行 — 现在在同一连接上顺序执行查询，以避免 pg 8.19.0 的弃用警告 (#12105 by @pkuczynski)

  • MySQL: PolarDB-X 2.0 版本检测 — 对于 PolarDB-X 2.0，getVersion() 不再返回 undefined (#11837 by @Missna)

  • MongoDB: ObjectIdColumn 属性名转换 — findOneBy({ id: value }) 现在在 MongoDB 查询中能正确转换为 _id (#12200 by @pkuczynski)

  • MongoDB：嵌套文档中的嵌入式数组 — 正确处理嵌套文档结构中的嵌入式数组 (#10940 by @mciuchitu)

  • SQLite：simple-enum 数组 — 带有 array: true 的 simple-enum 列不再因 CHECK 约束错误而失败 (#11865 by @Cprakhar)

  • SAP HANA：Date 参数转义 — JavaScript Date 值现在作为查询参数传递，不再嵌入 SQL 字符串 (#11867 by @alumni)

  • CockroachDB：事务重试中的结构化查询结果 — useStructuredResult 标志在 CockroachDB 事务重试重放期间会被保留 (#11861 by @naorpeled)

  • Cordova：查询受影响行数 — 查询结果现在包含受影响的行数统计 (#10873 by @jacobg)

其他​

  • CLI init 命令优化 — 当 package.json 不存在时不再崩溃 (#11947 by @gioboa)；发布的包现已正确包含脚手架所需的 devDependencies (#12281 by @pkuczynski)

  • Deno process 导入 — 修复了 Deno 环境下错误的 process 依赖导入 (#11248 by @yohannpoli)

安全修复​

  • SQL 注入防护 — 所有驱动在模式自省和 DDL 方法中均使用参数化查询和转义标识符，防止通过数据库/模式/表/列名进行 SQL 注入 (#12207 by @pkuczynski, #12197 by @pkuczynski, #12185 by @pkuczynski)

  • OrderBy 条件验证 — QueryBuilder 的 orderBy 和 addOrderBy 方法现会在运行时验证条件值，防止通过排序表达式注入攻击 (#12217 by @pkuczynski)

性能改进​

  • PostgreSQL / CockroachDB：clearDatabase() 中的批量 DROP — 将单独的 DROP 语句合并为批量查询，显著减少测试设置期间的往返次数 (#12164, #12159 by @pkuczynski)