README
Last updated
Last updated
TypeORM is an ORM that can run in NodeJS, Browser, Cordova, PhoneGap, Ionic, React Native, NativeScript, Expo, and Electron platforms and can be used with TypeScript and JavaScript (ES2021). Its goal is to always support the latest JavaScript features and provide additional features that help you to develop any kind of application that uses databases - from small applications with a few tables to large-scale enterprise applications with multiple databases.
TypeORM supports both Active Record and Data Mapper patterns, unlike all other JavaScript ORMs currently in existence, which means you can write high-quality, loosely coupled, scalable, maintainable applications in the most productive way.
TypeORM is highly influenced by other ORMs, such as Hibernate, Doctrine and Entity Framework.
📣 Announcement: The Future of TypeORM
We’re excited to share our vision for a revitalized TypeORM—a strategy focused on building a stable, robust, and sustainable foundation for the long term. Learn how we’re structuring maintenance and bringing together dedicated resources to ensure TypeORM thrives for years to come.
Supports both DataMapper and ActiveRecord (your choice).
Entities and columns.
Database-specific column types.
Entity manager.
Repositories and custom repositories.
Clean object-relational model.
Associations (relations).
Eager and lazy relations.
Uni-directional, bi-directional, and self-referenced relations.
Supports multiple inheritance patterns.
Cascades.
Indices.
Transactions.
Migrations and automatic migrations generation.
Connection pooling.
Replication.
Using multiple database instances.
Working with multiple database types.
Cross-database and cross-schema queries.
Elegant-syntax, flexible and powerful QueryBuilder.
Left and inner joins.
Proper pagination for queries using joins.
Query caching.
Streaming raw results.
Logging.
Listeners and subscribers (hooks).
Supports closure table pattern.
Schema declaration in models or separate configuration files.
Supports MySQL / MariaDB / Postgres / CockroachDB / SQLite / Microsoft SQL Server / Oracle / SAP Hana / sql.js.
Supports MongoDB NoSQL database.
Works in NodeJS / Browser / Ionic / Cordova / React Native / NativeScript / Expo / Electron platforms.
TypeScript and JavaScript support.
ESM and CommonJS support.
Produced code is performant, flexible, clean, and maintainable.
Follows all possible best practices.
CLI.
And more...
With TypeORM your models look like this:
And your domain logic looks like this:
Alternatively, if you prefer to use the ActiveRecord
implementation, you can use it as well:
And your domain logic will look this way:
Install the npm package:
npm install typeorm --save
You need to install reflect-metadata
shim:
npm install reflect-metadata --save
and import it somewhere in the global place of your app (for example in app.ts
):
import "reflect-metadata"
You may need to install node typings:
npm install @types/node --save-dev
Install a database driver:
for MySQL or MariaDB
npm install mysql --save
(you can install mysql2
instead as well)
for PostgreSQL or CockroachDB
npm install pg --save
for SQLite
npm install sqlite3 --save
for Microsoft SQL Server
npm install mssql --save
for sql.js
npm install sql.js --save
for Oracle
npm install oracledb --save
To make the Oracle driver work, you need to follow the installation instructions from their site.
for Google Cloud Spanner
Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS
:
To use Spanner with the emulator you should set SPANNER_EMULATOR_HOST
environment variable:
for MongoDB (experimental)
npm install mongodb@^5.2.0 --save
for NativeScript, react-native and Cordova
Install only one of them, depending on which database you use.
TypeScript configuration
Also, make sure you are using TypeScript version 4.5 or higher, and you have enabled the following settings in tsconfig.json
:
You may also need to enable es6
in the lib
section of compiler options, or install es6-shim
from @types
.
The quickest way to get started with TypeORM is to use its CLI commands to generate a starter project. Quick start works only if you are using TypeORM in a NodeJS application. If you are using other platforms, proceed to the step-by-step guide.
To create a new project using CLI, run the following command:
Where name
is the name of your project and database
is the database you'll use. Database can be one of the following values: mysql
, mariadb
, postgres
, cockroachdb
, sqlite
, mssql
, sap
, spanner
, oracle
, mongodb
, cordova
, react-native
, expo
, nativescript
.
This command will generate a new project in the MyProject
directory with the following files:
You can also run
typeorm init
on an existing node project, but be careful - it may override some files you already have.
The next step is to install new project dependencies:
After you have all dependencies installed, edit the data-source.ts
file and put your own database connection configuration options in there:
Particularly, most of the time you'll only need to configure host
, username
, password
, database
and maybe port
options.
Once you finish with configuration and all node modules are installed, you can run your application:
That's it, your application should successfully run and insert a new user into the database. You can continue to work with this project and integrate other modules you need and start creating more entities.
You can generate an ESM project by running
npx typeorm init --name MyProject --database postgres --module esm
command.
You can generate an even more advanced project with express installed by running
npx typeorm init --name MyProject --database mysql --express
command.
You can generate a docker-compose file by running
npx typeorm init --name MyProject --database postgres --docker
command.
What are you expecting from ORM? First of all, you are expecting it will create database tables for you and find / insert / update / delete your data without the pain of having to write lots of hardly maintainable SQL queries. This guide will show you how to set up TypeORM from scratch and make it do what you are expecting from an ORM.
Working with a database starts with creating tables. How do you tell TypeORM to create a database table? The answer is - through the models. Your models in your app are your database tables.
For example, you have a Photo
model:
And you want to store photos in your database. To store things in the database, first, you need a database table, and database tables are created from your models. Not all models, but only those you define as entities.
Entity is your model decorated by an @Entity
decorator. A database table will be created for such models. You work with entities everywhere in TypeORM. You can load/insert/update/remove and perform other operations with them.
Let's make our Photo
model an entity:
Now, a database table will be created for the Photo
entity and we'll be able to work with it anywhere in our app. We have created a database table, however, what table can exist without columns? Let's create a few columns in our database table.
To add database columns, you simply need to decorate an entity's properties you want to make into a column with a @Column
decorator.
Now id
, name
, description
, filename
, views
, and isPublished
columns will be added to the photo
table. Column types in the database are inferred from the property types you used, e.g. number
will be converted into integer
, string
into varchar
, boolean
into bool
, etc. But you can use any column type your database supports by explicitly specifying a column type into the @Column
decorator.
We generated a database table with columns, but there is one thing left. Each database table must have a column with a primary key.
Each entity must have at least one primary key column. This is a requirement and you can't avoid it. To make a column a primary key, you need to use the @PrimaryColumn
decorator.
Now, let's say you want your id column to be auto-generated (this is known as auto-increment / sequence / serial / generated identity column). To do that, you need to change the @PrimaryColumn
decorator to a @PrimaryGeneratedColumn
decorator:
Next, let's fix our data types. By default, the string is mapped to a varchar(255)-like type (depending on the database type). The number is mapped to an integer-like type (depending on the database type). We don't want all our columns to be limited varchars or integers. Let's setup the correct data types:
Column types are database-specific. You can set any column type your database supports. More information on supported column types can be found here.
DataSource
Now, when our entity is created, let's create index.ts
file and set up our DataSource
there:
We are using Postgres in this example, but you can use any other supported database. To use another database, simply change the type
in the options to the database type you are using: mysql
, mariadb
, postgres
, cockroachdb
, sqlite
, mssql
, oracle
, sap
, spanner
, cordova
, nativescript
, react-native
, expo
, or mongodb
. Also make sure to use your own host, port, username, password, and database settings.
We added our Photo entity to the list of entities for this data source. Each entity you are using in your connection must be listed there.
Setting synchronize
makes sure your entities will be synced with the database, every time you run the application.
Now if you run your index.ts
, a connection with the database will be initialized and a database table for your photos will be created.
Now let's create a new photo to save it in the database:
Once your entity is saved it will get a newly generated id. save
method returns an instance of the same object you pass to it. It's not a new copy of the object, it modifies its "id" and returns it.
We just created a new photo and saved it in the database. We used EntityManager
to save it. Using entity manager you can manipulate any entity in your app. For example, let's load our saved entity:
savedPhotos
will be an array of Photo objects with the data loaded from the database.
Learn more about EntityManager here.
Now let's refactor our code and use Repository
instead of EntityManager
. Each entity has its own repository which handles all operations with its entity. When you deal with entities a lot, Repositories are more convenient to use than EntityManagers:
Learn more about Repository here.
Let's try more load operations using the Repository:
Now let's load a single photo from the database, update it and save it:
Now photo with id = 1
will be updated in the database.
Now let's remove our photo from the database:
Now photo with id = 1
will be removed from the database.
Let's create a one-to-one relationship with another class. Let's create a new class in PhotoMetadata.ts
. This PhotoMetadata class is supposed to contain our photo's additional meta-information:
Here, we are using a new decorator called @OneToOne
. It allows us to create a one-to-one relationship between two entities. type => Photo
is a function that returns the class of the entity with which we want to make our relationship. We are forced to use a function that returns a class, instead of using the class directly, because of the language specifics. We can also write it as () => Photo
, but we use type => Photo
as a convention to increase code readability. The type variable itself does not contain anything.
We also add a @JoinColumn
decorator, which indicates that this side of the relationship will own the relationship. Relations can be unidirectional or bidirectional. Only one side of relational can be owning. Using @JoinColumn
decorator is required on the owner side of the relationship.
If you run the app, you'll see a newly generated table, and it will contain a column with a foreign key for the photo relation:
Now let's save a photo, and its metadata and attach them to each other.
Relations can be unidirectional or bidirectional. Currently, our relation between PhotoMetadata and Photo is unidirectional. The owner of the relation is PhotoMetadata, and Photo doesn't know anything about PhotoMetadata. This makes it complicated to access PhotoMetadata from the Photo side. To fix this issue we should add an inverse relation, and make relations between PhotoMetadata and Photo bidirectional. Let's modify our entities:
photo => photo.metadata
is a function that returns the name of the inverse side of the relation. Here we show that the metadata property of the Photo class is where we store PhotoMetadata in the Photo class. Instead of passing a function that returns a property of the photo, you could alternatively simply pass a string to @OneToOne
decorator, like "metadata"
. But we used this function-typed approach to make our refactoring easier.
Note that we should use the @JoinColumn
decorator only on one side of a relation. Whichever side you put this decorator on will be the owning side of the relationship. The owning side of a relationship contains a column with a foreign key in the database.
If you use ESM in your TypeScript project, you should use the Relation
wrapper type in relation properties to avoid circular dependency issues. Let's modify our entities:
Now let's load our photo and its photo metadata in a single query. There are two ways to do it - using find*
methods or using QueryBuilder
functionality. Let's use find*
method first. find*
methods allow you to specify an object with the FindOneOptions
/ FindManyOptions
interface.
Here, photos will contain an array of photos from the database, and each photo will contain its photo metadata. Learn more about Find Options in this documentation.
Using find options is good and dead simple, but if you need a more complex query, you should use QueryBuilder
instead. QueryBuilder
allows more complex queries to be used in an elegant way:
QueryBuilder
allows the creation and execution of SQL queries of almost any complexity. When you work with QueryBuilder
, think like you are creating an SQL query. In this example, "photo" and "metadata" are aliases applied to selected photos. You use aliases to access columns and properties of the selected data.
We can set up cascade options in our relations, in the cases when we want our related object to be saved whenever the other object is saved. Let's change our photo's @OneToOne
decorator a bit:
Using cascade
allows us not to separately save photos and separately save metadata objects now. Now we can simply save a photo object, and the metadata object will be saved automatically because of cascade options.
Notice that we now set the photo's metadata
property, instead of the metadata's photo
property as before. The cascade
feature only works if you connect the photo to its metadata from the photo's side. If you set the metadata side, the metadata would not be saved automatically.
Let's create a many-to-one/one-to-many relation. Let's say a photo has one author, and each author can have many photos. First, let's create an Author
class:
Author
contains an inverse side of a relation. OneToMany
is always an inverse side of the relation, and it can't exist without ManyToOne
on the other side of the relation.
Now let's add the owner side of the relation into the Photo entity:
In many-to-one / one-to-many relations, the owner side is always many-to-one. It means that the class that uses @ManyToOne
will store the id of the related object.
After you run the application, the ORM will create the author
table:
It will also modify the photo
table, adding a new author
column and creating a foreign key for it:
Let's create a many-to-many relation. Let's say a photo can be in many albums, and each album can contain many photos. Let's create an Album
class:
@JoinTable
is required to specify that this is the owner side of the relationship.
Now let's add the inverse side of our relation to the Photo
class:
After you run the application, the ORM will create a album_photos_photo_albums junction table:
Don't forget to register the Album
class with your connection in the ORM:
Now let's insert albums and photos into our database:
loadedPhoto
will be equal to: