API with NestJS #67. Migrating to TypeORM 0.3


This entry is part 67 of 158 in the API with NestJS

For a long time, TypeORM seemed to have a reputation of being somewhat stagnant. Lately, they stepped up their game, though, and started releasing many new versions. When doing that, they introduced a large number of breaking changes. In this article, we go through the most significant differences between 0.2.x and 0.3.x versions so far and see how they affect NestJS projects.

When writing this article, I was using TypeORM 0.3.7 and @nestjs/typeorm 8.1.4

Changes made to the repository API

TypeORM made a few changes to the functions we use to query the data.

Changes to the findOne method

First, they got rid of the function returning the first row from the table when not provided with an argument. It was caused by being confusing.

What’s more, TypeORM dropped the support for using to make the syntax more consistent. So now, we can only use by providing it with an object.

Because of all of the above, the following code no longer works:

error TS2554: Expected 1 arguments, but got 2.

Instead, we must pass a single object to the method.

To see all of the available options, check out the FindOneOptions interface.

Although the above code with still works, it is now deprecated and will soon be removed. Instead, we should use a new object-literal notation.

If we want to load a nested relation, we can create an object like this one:

Changes to the find method

TypeORM made a similar set of changes to the method. Because of that, the following code is no longer valid:

error TS2345: Argument of type is not assignable to parameter of type .

Instead, we need to provide the object explicitly.

Besides the and methods, similar changes happened to , , and .

Using the new findOneBy and findBy functions

When querying data, we don’t always need additional options, such as . In that case, we can use the new method.

Similarly, we can use the new method if we want to find multiple entities and don’t need to provide additional options such as .

Besides the above, we also have new , , and functions.

Deprecating the findByIds method

The is now deprecated and will soon be removed. Instead, we can use the method with the operator.

Renaming Connection to DataSource

Before TypeORM 0.3.0, the configuration with our database used to be called a . Recently, TypeORM renamed it to .

Throughout this series, we didn’t interact with the much except for working with transactions.


Unfortunately, the above code is no longer valid. Instead of , we should use instead.


Changes to the configuration

TypeORM made a few significant changes to how we configure our database connection. First, let’s take a look at our current configuration.


Unfortunately, strings with , , and is now deprecated. Therefore, in future TypeORM versions, we will be able only to use entity references.


Having to list all of our entities might be a bit troublesome. Fortunately, implements the option that we can use to auto-load entities.


Please notice that we still include the entity in the array above. The above is because we need to manually add every entity we don’t use through . In our case, a good example is the entity we use only through a one-to-one relationship.

New array operators

Previously, we had to use raw SQL to run more advanced queries with PostgreSQL arrays.

Now, TypeORM 0.3.1 introduced new array operators that can let us handle such cases.

Besides the above, we also have the and operators.

Other changes

Besides all the changes mentioned so far, TypeORM fixed a ton of minor and significant issues and added performance improvements.

It is worth tracking the changelog in the GitHub releases page.

Some of the important changes are:


In this article, we’ve gone through the most significant changes made to TypeORM in the last changes. Some of them forced us to refactor our code to be able to bump the TypeORM version we use. All the changes we’ve handled in this article seem like steps in the right direction. A crucial thing to remember is that TypeORM does not follow semantic versioning. Because of that, going from 0.3.0 to 0.3.1 can include breaking changes, for example. Because of that, we need to be super careful when updating TypeORM and read the changelog very carefully to see if it affects our project.

Series Navigation<< API with NestJS #66. Improving PostgreSQL performance with indexes using MikroORMAPI with NestJS #68. Interacting with the application through REPL >>
Notify of
Newest Most Voted
Inline Feedbacks
View all comments
2 years ago

What about custom repositories with Nestjs?

definitely robby krieger
definitely robby krieger
2 years ago
Reply to  Amr

What a coincidence. I am having issues with custom repositories too. I am trying this structure. But i got error like below;

Cannot read properties of undefined (reading ‘findOne’)

When i try to console.log it i am getting below;

You can see the code below:

We probably say to nestjs “hey this is a repository initialize it for us” 😀

1 year ago
Reply to  Amr

Same issue for me here. I would love to get a solution.

2 years ago

Nice post, recently I was suffering with configurations, What about migrations config? I guess this was a breaking change also, how do you manage it?

2 years ago
Reply to  Luga97

I know only NestJS + Typeorm + Many Crutches = Migrations 🙁 Please show good way.

1 year ago

Thank you. This is so insightful!

1 year ago

An example setup is here.


Any feedbacks are welcome!

1 year ago

Thank you very much. But can you help for another topic relating to this one, after upgrading to version 0.3 typeorm destroyed a lot of old approaches. Can you share how can we can create custom repository for entities for typeorm 0.3