Knowledge base
CodexGuild Knowledge Base

TypeORM 1.x: upgrading from 0.3 (Node 20+, removed Connection/global APIs, driver changes)

as of Sep 1, 2026 · applies to typeorm >= 1.0.0 · canonical · codexguild.com/kb/kb-typeorm-v1-upgrade-2026 · exported 2026-10-11
Canonical as of Sep 1, 2026

TypeORM 1.x: upgrading from 0.3 (Node 20+, removed Connection/global APIs, driver changes)

TypeORM 1.0.0 shipped 2026-05-19 (current 1.1.1, 2026-09-01). It requires Node 20+, removes Connection and all global helpers, drops string-based find options, sqlite3 and mysql drivers, and now throws on null/undefined where values. A codemod exists.

TypeORM 1.x upgrade from 0.3

As of: 2026-10

Versions

  • typeorm@1.0.0 was released 2026-05-19. 1.1.0 followed on 2026-07-13 and 1.1.1 (npm latest) on 2026-09-01.
  • The 0.3 line is in maintenance under the npm legacy tag; its newest release is 0.3.31 (2026-07-13).
  • Requirements: Node.js 20+ and a JavaScript target of ES2023. On non-Node platforms, Buffer is replaced with Uint8Array.

Automated migration

npx @typeorm/codemod v1 src/        # add --dry to preview

The codemod handles most renames, such as connection to dataSource, and flags patterns it cannot rewrite.

Removed APIs and their replacements

Removed (0.3)Use in 1.x
Connection, ConnectionOptions, ConnectionManagerDataSource, DataSourceOptions
Global getRepository(), getManager(), getConnection()dataSource.getRepository(), dataSource.manager
findByIds([...])findBy({ id: In([...]) })
findOneById(id)findOneBy({ id })
@EntityRepository, AbstractRepository, getCustomRepositorydataSource.getRepository(E).extend({...})
select: ["id"], relations: ["posts"] (string arrays), join find optionselect: { id: true }, relations: { posts: true }
TYPEORM_* env vars / ConnectionOptionsEnvReaderan explicit TS/JS DataSource file

Also removed: Repository.exist(), @RelationCount, the IoC container system, QueryBuilder.onConflict(), the deprecated orUpdate() overload, and setNativeParameters(). The connection property was also renamed to dataSource on EntityManager, QueryBuilder, QueryRunner, Driver, the metadata classes and the subscriber event objects.

Driver changes

  • MySQL/MariaDB: only mysql2 is supported, so remove the mysql package. Integer display width and zerofill were removed. legacySpatialSupport now defaults to false.
  • SQLite: sqlite3 was dropped and better-sqlite3 is now the default. The busyTimeout option was renamed to timeout.
  • MongoDB: requires driver v7+, and the deprecated connection options were removed.
  • SQL Server: the domain option was removed. Use authentication: { type: "ntlm", ... } instead.
  • The legacy Expo driver and support for old Redis client versions were removed.

Behaviour changes that break silently

  • invalidWhereValuesBehavior now throws on null/undefined in where. Previously the condition was dropped, which could turn into a full-table match. Use IsNull() for intentional NULL checks:
repo.findBy({ deletedAt: IsNull() });   // not { deletedAt: null }

1.1.0 also applies the throw default to write paths and rejects empty where criteria on QueryBuilder update/delete.

  • Relations declared nullable: false are loaded with INNER JOIN instead of LEFT JOIN.
  • Cascade remove on one-to-many relations now works, including with composite primary keys. Code that relied on rows not being cascaded will behave differently.

What to do now

  • New projects: use typeorm@^1.1 with a DataSource and object-syntax find options.
  • 0.3 projects: upgrade Node, run the codemod, and swap the sqlite3/mysql packages. Then search for null values inside where objects before deploying.

Sources