CHANGELOG
- new virtual column decorator (#9339) (d305e5f), closes #9323 typeorm#9323 typeorm#9323 typeorm#9323 typeorm#9323​
- support for TypeScript 4.8 (#9106) (d924b70), closes /github.com/microsoft/TypeScript/issues/49461#issuecomment-1154443477​
- we do not call JSON.stringify() to json/jsonb column types in Postgres. Instead, we delegate value directly to underlying pg driver. This is a correct way of handling jsons.
- array: true must be explicitly defined for array json/jsonb values
- strings being JSON-stringified must be manually escaped
Changes in the version includes changes from the
next branch and [email protected] version. They were pending their migration from 2018. Finally, they are in the master branch and master version.- compilation
targetnow ises2020. This requires Node.JS version14+ - TypeORM now properly works when installed within different node_modules contexts (often happen if TypeORM is a dependency of another library or TypeORM is heavily used in monorepo projects)
Connectionwas renamed toDataSource. OldConnectionis still there, but now it's deprecated. It will be completely removed in next version. New API:
export const dataSource = new DataSource({
// ... options ...
})
​
// load entities, establish db connection, sync schema, etc.
await dataSource.connect()
Previously, you could use
new Connection(), createConnection(), getConnectionManager().create(), etc. They all deprecated in favour of new syntax you can see above.New way gives you more flexibility and simplicity in usage.
- new custom repositories syntax:
export const UserRepository = myDataSource.getRepository(UserEntity).extend({
findUsersWithPhotos() {
return this.find({
relations: {
photos: true
}
})
}
})
Old ways of custom repository creation were dropped.
- added new option on relation load strategy called
relationLoadStrategy. Relation load strategy is used on entity load and determines how relations must be loaded when you query entities and their relations from the database. Used onfind*methods andQueryBuilder. Value can be set tojoinorquery.join- loads relations using SQLJOINexpressionquery- executes separate SQL queries for each relation
Default is
join, but default can be set in ConnectionOptions:createConnection({
/* ... */
relationLoadStrategy: "query"
})
Also, it can be set per-query in
find* methods:userRepository.find({
relations: {
photos: true
}
})
And QueryBuilder:
userRepository
.createQueryBuilder()
.setRelationLoadStrategy("query")
For queries returning big amount of data, we recommend to use
query strategy, because it can be a more performant approach to query relations.- added new
findOneBy,findOneByOrFail,findBy,countBy,findAndCountBymethods toBaseEntity,EntityManagerandRepository:
const users = await userRepository.findBy({
name: "Michael"
})
Overall
find* and count* method signatures where changed, read the "breaking changes" section for more info.- new
selecttype signature inFindOptions(used infind*methods):
userRepository.find({
select: {
id: true,
firstName: true,
lastName: true,
}
})
Also, now it's possible to specify select columns of the loaded relations:
userRepository.find({
select: {
id: true,
firstName: true,
lastName: true,
photo: {
id: true,
filename: true,
album: {
id: true,
name: true,
}
}
}
})
- new
relationstype signature inFindOptions(used infind*methods):
userRepository.find({
relations: {
contacts: true,
photos: true,
}
})
To load nested relations use a following signature:
userRepository.find({
relations: {
contacts: true,
photos: {
album: true,
},
}
})
- new
ordertype signature inFindOptions(used infind*methods):
userRepository.find({
order: {
id: "ASC"
}
})
Now supports nested order by-s:
userRepository.find({
order: {
photos: {
album: {
name: "ASC"
},
},
}
})
- new
wheretype signature inFindOptions(used infind*methods) now allows to build nested statements with conditional relations, for example:
userRepository.find({
where: {
photos: {
album: {
name: "profile"
}
}
}
})
Gives you users who have photos in their "profile" album.
FindOperator-s can be applied for relations inwherestatement, for example:
userRepository.find({
where: {
photos: MoreThan(10),
}
})
Gives you users with more than 10 photos.
booleancan be applied for relations inwherestatement, for example:
userRepository.find({
where: {
photos: true
}
})
- minimal Node.JS version requirement now is
14+ - drop
ormconfigsupport.ormconfigstill works if you use deprecated methods, however we do not recommend using it anymore, because it's support will be completely dropped in0.4.0. If you want to have your connection options defined in a separate file, you can still do it like this:
import ormconfig from "./ormconfig.json"
​
const MyDataSource = new DataSource(require("./ormconfig.json"))
Or even more type-safe approach with
resolveJsonModule in tsconfig.json enabled:import ormconfig from "./ormconfig.json"
​
const MyDataSource = new DataSource(ormconfig)
But we do not recommend use this practice, because from
0.4.0 you'll only be able to specify entities / subscribers / migrations using direct references to entity classes / schemas (see "deprecations" section).We won't be supporting all
ormconfig extensions (e.g. json, js, ts, yaml, xml, env).- support for previously deprecated
migrations:*commands was removed. Usemigration:*commands instead. - all commands were re-worked. Please refer to new CLI documentation.
clioption fromBaseConnectionOptions(nowBaseDataSourceOptionsoptions) was removed (since CLI commands were re-worked).- now migrations are running before schema synchronization if you have both pending migrations and schema synchronization pending (it works if you have both
migrationsRunandsynchronizeenabled in connection options). aurora-data-apidriver now is calledaurora-mysqlaurora-data-api-pgdriver now is calledaurora-postgresEntityManager.connectionis nowEntityManager.dataSourceRepositorynow has a constructor (breaks classes extending Repository with custom constructor)@TransactionRepository,@TransactionManager,@Transactiondecorators were completely removed. These decorators do the things out of the TypeORM scope.- Only junction table names shortened.
MOTIVATION: We must shorten only table names generated by TypeORM. It's user responsibility to name tables short if their RDBMS limit table name length since it won't make sense to have table names as random hashes. It's really better if user specify custom table name into
@Entity decorator. Also, for junction table it's possible to set a custom name using @JoinTable decorator.findOne()signature without parameters was dropped. If you need a single row from the db you can use a following syntax:
const [user] = await userRepository.find()
findOne(id)signature was dropped. Use following syntax instead:
const user = await userRepository.findOneBy({
id: id // where id is your column name
})
This change was made to provide a more type-safe approach for data querying. Due to this change you might need to refactor the way you load entities using MongoDB driver.
findOne,findOneOrFail,find,count,findAndCountmethods now only acceptFindOptionsas parameter, e.g.:
const users = await userRepository.find({
where: { /* conditions */ },
relations: { /* relations */ }
})
To supply
where conditions directly without FindOptions new methods were added: findOneBy, findOneByOrFail, findBy, countBy, findAndCountBy. Example:const users = await userRepository.findBy({
name: "Michael"
})
This change was required to simply current
find* and count* methods typings, improve type safety and prevent user confusion.findByIdswas deprecated, usefindBymethod instead in conjunction withInoperator, for example:
userRepository.findBy({
id: In([1, 2, 3])
})
This change was made to provide a more type-safe approach for data querying.
findOneandQueryBuilder.getOne()now returnnullinstead ofundefinedin the case if it didn't find anything in the database. Logically it makes more sense to returnnull.findOnenow limits returning rows to 1 at database level.
NOTE:
FOR UPDATE locking does not work with findOne in Oracle since FOR UPDATE cannot be used with FETCH NEXT in a single query.whereinFindOptions(e.g.find({ where: { ... })) is more sensitive to input criteria now.FindConditions(whereinFindOptions) was renamed toFindOptionsWhere.nullas value inwhereused infind*methods is not supported anymore. Now you must explicitly useIsNull()operator.
Before:
userRepository.find({
where: {
photo: null
}
})
After:
userRepository.find({
where: {
photo: IsNull()
}
})
This change was made to make it more transparent on how to add "IS NULL" statement to final SQL, because before it bring too much confusion for ORM users.
- if you had entity properties of a non-primitive type (except Buffer) defined as columns, then you won't be able to use it in
find*'swhere. Example:
Before for the
@Column(/*...*/) membership: MembershipKind you could have a query like:userRepository.find({
membership: new MembershipKind("premium")
})
now, you need to wrap this value into
Equal operator:userRepository.find({
membership: Equal(new MembershipKind("premium"))
})
This change is due to type-safety improvement new
where signature brings.orderinFindOptions(used infind*methods) doesn't support ordering by relations anymore. Define relation columns, and order by them instead.whereinFindOptions(used infind*methods) previously supportedObjectLiteralandstringtypes. Now both signatures were removed. ObjectLiteral was removed because it seriously breaks the type safety, andstringdoesn't make sense in the context ofFindOptions. UseQueryBuilderinstead.MongoRepositoryandMongoEntityManagernow use new types calledMongoFindManyOptionsandMongoFindOneOptionsfor theirfind*methods.primary relation(e.g.@ManyToOne(() => User, { primary: true }) user: User) support is removed. You still have an ability to use foreign keys as your primary keys, however now you must explicitly define a column marked as primary.
Example, before:
@ManyToOne(() => User, { primary: true })
user: User
Now:
@PrimaryColumn()
userId: number
​
@ManyToOne(() => User)
user: User
Primary column name must match the relation name + join column name on related entity. If related entity has multiple primary keys, and you want to point to multiple primary keys, you can define multiple primary columns the same way:
@PrimaryColumn()
userFirstName: string
​
@PrimaryColumn()
userLastName: string
​
@ManyToOne(() => User)
user: User
This change was required to simplify ORM internals and introduce new features.
- all CLI commands do not support
ormconfiganymore. You must specify a file with data source instance instead. entities,migrations,subscribersoptions insideDataSourceOptionsacceptingstringdirectories support is deprecated. You'll be only able to pass entity references in the future versions.- all container-related features (
UseContainerOptions,ContainedType,ContainerInterface,defaultContainer,useContainer,getFromContainer) are deprecated. - EntityManager's
getCustomRepositoryused within transactions is deprecated. UsewithRepositorymethod instead. Connection.isConnectedis deprecated. Use.isInitializedinstead.selectinFindOptions(used infind*methods) used as an array of property names is deprecated. Now you should use a new object-literal notation. Example:
Deprecated way of loading entity relations:
userRepository.find({
select: ["id", "firstName", "lastName"]
})
New way of loading entity relations:
userRepository.find({
select: {
id: true,
firstName: true,
lastName: true,
}
})
This change is due to type-safety improvement new
select signature brings.relationsinFindOptions(used infind*methods) used as an array of relation names is deprecated. Now you should use a new object-literal notation. Example:
Deprecated way of loading entity relations:
userRepository.find({
relations: ["contacts", "photos", "photos.album"]
})
New way of loading entity relations:
userRepository.find({
relations: {
contacts: true,
photos: {
album: true
}
}
})
This change is due to type-safety improvement new
relations signature brings.joininFindOptions(used infind*methods) is deprecated. UseQueryBuilderto build queries containing manual joins.