Github url

typeorm

by typeorm

typeorm /typeorm

ORM for TypeScript and JavaScript (ES7, ES6, ES5). Supports MySQL, PostgreSQL, MariaDB, SQLite, MS S...

19.9K Stars 3.2K Forks Last release: Not found MIT License 4.3K Commits 55 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

Codecov

TypeORM is an ORMthat can run in NodeJS, Browser, Cordova, PhoneGap, Ionic, React Native, NativeScript, Expo, and Electron platforms and can be used with TypeScript and JavaScript (ES5, ES6, ES7, ES8). 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 the most productive way.

TypeORM is highly influenced by other ORMs, such as Hibernate, Doctrine and Entity Framework.

Some TypeORM features:

  • 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 connections
  • working with multiple databases 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
  • connection configuration in json / xml / yml / env formats
  • 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
  • produced code is performant, flexible, clean and maintainable
  • follows all possible best practices
  • CLI

And more...

With TypeORM your models look like this:

import {Entity, PrimaryGeneratedColumn, Column} from "typeorm"; @Entity() export class User { @PrimaryGeneratedColumn() id: number; @Column() firstName: string; @Column() lastName: string; @Column() age: number; }

And your domain logic looks like this:

const repository = connection.getRepository(User); const user = new User(); user.firstName = "Timber"; user.lastName = "Saw"; user.age = 25; await repository.save(user); const allUsers = await repository.find(); const firstUser = await repository.findOne(1); // find by id const timber = await repository.findOne({ firstName: "Timber", lastName: "Saw" }); await repository.remove(timber);

Alternatively, if you prefer to use the

ActiveRecord

implementation, you can use it as well:

import {Entity, PrimaryGeneratedColumn, Column, BaseEntity} from "typeorm"; @Entity() export class User extends BaseEntity { @PrimaryGeneratedColumn() id: number; @Column() firstName: string; @Column() lastName: string; @Column() age: number; }

And your domain logic will look this way:

const user = new User(); user.firstName = "Timber"; user.lastName = "Saw"; user.age = 25; await user.save(); const allUsers = await User.find(); const firstUser = await User.findOne(1); const timber = await User.findOne({ firstName: "Timber", lastName: "Saw" }); await timber.remove();

Installation

  1. Install the npm package:

npm install typeorm --save
  1. 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";
  1. You may need to install node typings:

npm install @types/node --save
  1. 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](https://github.com/oracle/node-oracledb) site. \* for \*\*SAP Hana\*\* ``` npm config set @sap:registry https://npm.sap.com npm i @sap/hana-client npm i hdb-pool ``` \*SAP Hana support made possible by sponsorship of [Neptune Software](https://www.neptune-software.com/).\* \* for \*\*MongoDB\*\* (experimental) `npm install mongodb --save` \* for \*\*NativeScript\*\*, \*\*react-native\*\* and \*\*Cordova\*\* Check [documentation of supported platforms](./docs/supported-platforms.md) Install only \*one\* of them, depending on which database you use.
TypeScript configuration

Also, make sure you are using TypeScript version 3.3 or higher, and you have enabled the following settings in

tsconfig.json

:

"emitDecoratorMetadata": true, "experimentalDecorators": true,

You may also need to enable

es6

in the

lib

section of compiler options, or install

es6-shim

from

@types

.

Quick Start

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.

First, install TypeORM globally:

npm install typeorm -g

Then go to the directory where you want to create a new project and run the command:

typeorm init --name MyProject --database mysql

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

,

oracle

,

mongodb

,

cordova

,

react-native

,

expo

,

nativescript

.

This command will generate a new project in the

MyProject

directory with the following files:

MyProject ├── src // place of your TypeScript code │ ├── entity // place where your entities (database models) are stored │ │ └── User.ts // sample entity │ ├── migration // place where your migrations are stored │ └── index.ts // start point of your application ├── .gitignore // standard gitignore file ├── ormconfig.json // ORM and database connection configuration ├── package.json // node module dependencies ├── README.md // simple readme file └── tsconfig.json // TypeScript compiler options

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:

cd MyProject npm install

While installation is in progress, edit the

ormconfig.json

file and put your own database connection configuration options in there:

{ "type": "mysql", "host": "localhost", "port": 3306, "username": "test", "password": "test", "database": "test", "synchronize": true, "logging": false, "entities": ["src/entity/\*\*/\*.ts"], "migrations": ["src/migration/\*\*/\*.ts"], "subscribers": ["src/subscriber/\*\*/\*.ts"] }

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:

npm start

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 even more advanced project with express installed by running

typeorm init --name MyProject --database mysql --express

command.

Step-by-Step Guide

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 setup TypeORM from scratch and make it do what you are expecting from an ORM.

Create a model

Working with a database starts from 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:

export class Photo { id: number; name: string; description: string; filename: string; views: number; isPublished: boolean; }

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.

Create an entity

Entity is your model decorated by an

@Entity

decorator. A database table will be created for such models. You work with entities everywhere with TypeORM. You can load/insert/update/remove and perform other operations with them.

Let's make our

Photo

model as an entity:

import {Entity} from "typeorm"; @Entity() export class Photo { id: number; name: string; description: string; filename: string; views: number; isPublished: boolean; }

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.

Adding table columns

To add database columns, you simply need to decorate an entity's properties you want to make into a column with a

@Column

decorator.

import {Entity, Column} from "typeorm"; @Entity() export class Photo { @Column() id: number; @Column() name: string; @Column() description: string; @Column() filename: string; @Column() views: number; @Column() isPublished: boolean; }

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.

Creating a primary column

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

@PrimaryColumn

decorator.

import {Entity, Column, PrimaryColumn} from "typeorm"; @Entity() export class Photo { @PrimaryColumn() id: number; @Column() name: string; @Column() description: string; @Column() filename: string; @Column() views: number; @Column() isPublished: boolean; }

Creating an auto generated column

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:

import {Entity, Column, PrimaryGeneratedColumn} from "typeorm"; @Entity() export class Photo { @PrimaryGeneratedColumn() id: number; @Column() name: string; @Column() description: string; @Column() filename: string; @Column() views: number; @Column() isPublished: boolean; }

Column data types

Next, let's fix our data types. By default, string is mapped to a varchar(255)-like type (depending on the database type). Number is mapped to a integer-like type (depending on the database type). We don't want all our columns to be limited varchars or integers. Let's setup correct data types:

import {Entity, Column, PrimaryGeneratedColumn} from "typeorm"; @Entity() export class Photo { @PrimaryGeneratedColumn() id: number; @Column({ length: 100 }) name: string; @Column("text") description: string; @Column() filename: string; @Column("double") views: number; @Column() isPublished: boolean; }

Column types are database-specific. You can set any column type your database supports. More information on supported column types can be found here.

Creating a connection to the database

Now, when our entity is created, let's create an

index.ts

(or

app.ts

whatever you call it) file and set up our connection there:

import "reflect-metadata"; import {createConnection} from "typeorm"; import {Photo} from "./entity/Photo"; createConnection({ type: "mysql", host: "localhost", port: 3306, username: "root", password: "admin", database: "test", entities: [Photo], synchronize: true, logging: false }).then(connection =\> { // here you can start to work with your entities }).catch(error =\> console.log(error));

We are using MySQL 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

,

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 connection. 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.

Loading all entities from the directory

Later, when we create more entities we need to add them to the entities in our configuration. This is not very convenient, so instead we can set up the whole directory, from where all entities will be connected and used in our connection:

import {createConnection} from "typeorm"; createConnection({ type: "mysql", host: "localhost", port: 3306, username: "root", password: "admin", database: "test", entities: [\_\_dirname + "/entity/\*.js"], synchronize: true, }).then(connection =\> { // here you can start to work with your entities }).catch(error =\> console.log(error));

But be careful with this approach. If you are using

ts-node

then you need to specify paths to

.ts

files instead. If you are using

outDir

then you'll need to specify paths to

.js

files inside outDir directory. If you are using

outDir

and when you remove or rename your entities make sure to clear

outDir

directory and re-compile your project again, because when you remove your source

.ts

files their compiled

.js

versions aren't removed from output directory and still are loaded by TypeORM because they are present in the

outDir

directory.

Running the application

Now if you run your

index.ts

, a connection with database will be initialized and a database table for your photos will be created.

+-------------+--------------+----------------------------+ | photo | +-------------+--------------+----------------------------+ | id | int(11) | PRIMARY KEY AUTO\_INCREMENT | | name | varchar(100) | | | description | text | | | filename | varchar(255) | | | views | int(11) | | | isPublished | boolean | | +-------------+--------------+----------------------------+

Creating and inserting a photo into the database

Now let's create a new photo to save it in the database:

import {createConnection} from "typeorm"; import {Photo} from "./entity/Photo"; createConnection(/\*...\*/).then(connection =\> { let photo = new Photo(); photo.name = "Me and Bears"; photo.description = "I am near polar bears"; photo.filename = "photo-with-bears.jpg"; photo.views = 1; photo.isPublished = true;    return connection.manager .save(photo) .then(photo =\> { console.log("Photo has been saved. Photo id is", photo.id); }); }).catch(error =\> console.log(error));

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.

Using async/await syntax

Let's take advantage of the latest ES8 (ES2017) features and use async/await syntax instead:

import {createConnection} from "typeorm"; import {Photo} from "./entity/Photo"; createConnection(/\*...\*/).then(async connection =\> { let photo = new Photo(); photo.name = "Me and Bears"; photo.description = "I am near polar bears"; photo.filename = "photo-with-bears.jpg"; photo.views = 1; photo.isPublished = true; await connection.manager.save(photo); console.log("Photo has been saved"); }).catch(error =\> console.log(error));

Using Entity Manager

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:

import {createConnection} from "typeorm"; import {Photo} from "./entity/Photo"; createConnection(/\*...\*/).then(async connection =\> { /\*...\*/ let savedPhotos = await connection.manager.find(Photo); console.log("All photos from the db: ", savedPhotos); }).catch(error =\> console.log(error));
savedPhotos

will be an array of Photo objects with the data loaded from the database.

Learn more about EntityManager here.

Using Repositories

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:

import {createConnection} from "typeorm"; import {Photo} from "./entity/Photo"; createConnection(/\*...\*/).then(async connection =\> { let photo = new Photo(); photo.name = "Me and Bears"; photo.description = "I am near polar bears"; photo.filename = "photo-with-bears.jpg"; photo.views = 1; photo.isPublished = true; let photoRepository = connection.getRepository(Photo); await photoRepository.save(photo); console.log("Photo has been saved"); let savedPhotos = await photoRepository.find(); console.log("All photos from the db: ", savedPhotos); }).catch(error =\> console.log(error));

Learn more about Repository here.

Loading from the database

Let's try more load operations using the Repository:

import {createConnection} from "typeorm"; import {Photo} from "./entity/Photo"; createConnection(/\*...\*/).then(async connection =\> { /\*...\*/ let allPhotos = await photoRepository.find(); console.log("All photos from the db: ", allPhotos); let firstPhoto = await photoRepository.findOne(1); console.log("First photo from the db: ", firstPhoto); let meAndBearsPhoto = await photoRepository.findOne({ name: "Me and Bears" }); console.log("Me and Bears photo from the db: ", meAndBearsPhoto); let allViewedPhotos = await photoRepository.find({ views: 1 }); console.log("All viewed photos: ", allViewedPhotos); let allPublishedPhotos = await photoRepository.find({ isPublished: true }); console.log("All published photos: ", allPublishedPhotos); let [allPhotos, photosCount] = await photoRepository.findAndCount(); console.log("All photos: ", allPhotos); console.log("Photos count: ", photosCount); }).catch(error =\> console.log(error));

Updating in the database

Now let's load a single photo from the database, update it and save it:

import {createConnection} from "typeorm"; import {Photo} from "./entity/Photo"; createConnection(/\*...\*/).then(async connection =\> { /\*...\*/ let photoToUpdate = await photoRepository.findOne(1); photoToUpdate.name = "Me, my friends and polar bears"; await photoRepository.save(photoToUpdate); }).catch(error =\> console.log(error));

Now photo with

id = 1

will be updated in the database.

Removing from the database

Now let's remove our photo from the database:

import {createConnection} from "typeorm"; import {Photo} from "./entity/Photo"; createConnection(/\*...\*/).then(async connection =\> { /\*...\*/ let photoToRemove = await photoRepository.findOne(1); await photoRepository.remove(photoToRemove); }).catch(error =\> console.log(error));

Now photo with

id = 1

will be removed from the database.

Creating a one-to-one relation

Let's create a one-to-one relation 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:

import {Entity, Column, PrimaryGeneratedColumn, OneToOne, JoinColumn} from "typeorm"; import {Photo} from "./Photo"; @Entity() export class PhotoMetadata { @PrimaryGeneratedColumn() id: number; @Column("int") height: number; @Column("int") width: number; @Column() orientation: string; @Column() compressed: boolean; @Column() comment: string; @OneToOne(type =\> Photo) @JoinColumn() photo: Photo; }

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:

+-------------+--------------+----------------------------+ | photo\_metadata | +-------------+--------------+----------------------------+ | id | int(11) | PRIMARY KEY AUTO\_INCREMENT | | height | int(11) | | | width | int(11) | | | comment | varchar(255) | | | compressed | boolean | | | orientation | varchar(255) | | | photoId | int(11) | FOREIGN KEY | +-------------+--------------+----------------------------+

Save a one-to-one relation

Now let's save a photo, its metadata and attach them to each other.

import {createConnection} from "typeorm"; import {Photo} from "./entity/Photo"; import {PhotoMetadata} from "./entity/PhotoMetadata"; createConnection(/\*...\*/).then(async connection =\> { // create a photo let photo = new Photo(); photo.name = "Me and Bears"; photo.description = "I am near polar bears"; photo.filename = "photo-with-bears.jpg"; photo.isPublished = true; // create a photo metadata let metadata = new PhotoMetadata(); metadata.height = 640; metadata.width = 480; metadata.compressed = true; metadata.comment = "cybershoot"; metadata.orientation = "portrait"; metadata.photo = photo; // this way we connect them // get entity repositories let photoRepository = connection.getRepository(Photo); let metadataRepository = connection.getRepository(PhotoMetadata); // first we should save a photo await photoRepository.save(photo); // photo is saved. Now we need to save a photo metadata await metadataRepository.save(metadata); // done console.log("Metadata is saved, and relation between metadata and photo is created in the database too"); }).catch(error =\> console.log(error));

Inverse side of the relationship

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:

import {Entity, Column, PrimaryGeneratedColumn, OneToOne, JoinColumn} from "typeorm"; import {Photo} from "./Photo"; @Entity() export class PhotoMetadata { /\* ... other columns \*/ @OneToOne(type =\> Photo, photo =\> photo.metadata) @JoinColumn() photo: Photo; }
import {Entity, Column, PrimaryGeneratedColumn, OneToOne} from "typeorm"; import {PhotoMetadata} from "./PhotoMetadata"; @Entity() export class Photo { /\* ... other columns \*/ @OneToOne(type =\> PhotoMetadata, photoMetadata =\> photoMetadata.photo) metadata: PhotoMetadata; }
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

@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.

Loading objects with their relations

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\*

methods first.

find\*

methods allow you to specify an object with the

FindOneOptions

/

FindManyOptions

interface.

import {createConnection} from "typeorm"; import {Photo} from "./entity/Photo"; import {PhotoMetadata} from "./entity/PhotoMetadata"; createConnection(/\*...\*/).then(async connection =\> { /\*...\*/ let photoRepository = connection.getRepository(Photo); let photos = await photoRepository.find({ relations: ["metadata"] }); }).catch(error =\> console.log(error));

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:

import {createConnection} from "typeorm"; import {Photo} from "./entity/Photo"; import {PhotoMetadata} from "./entity/PhotoMetadata"; createConnection(/\*...\*/).then(async connection =\> { /\*...\*/ let photos = await connection .getRepository(Photo) .createQueryBuilder("photo") .innerJoinAndSelect("photo.metadata", "metadata") .getMany(); }).catch(error =\> console.log(error));
QueryBuilder

allows 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.

Using cascades to automatically save related objects

We can setup 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:

export class Photo { /// ... other columns @OneToOne(type =\> PhotoMetadata, metadata =\> metadata.photo, { cascade: true, }) metadata: PhotoMetadata; }

Using

cascade

allows us not to separately save photo 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.

createConnection(options).then(async connection =\> { // create photo object let photo = new Photo(); photo.name = "Me and Bears"; photo.description = "I am near polar bears"; photo.filename = "photo-with-bears.jpg"; photo.isPublished = true; // create photo metadata object let metadata = new PhotoMetadata(); metadata.height = 640; metadata.width = 480; metadata.compressed = true; metadata.comment = "cybershoot"; metadata.orientation = "portait"; photo.metadata = metadata; // this way we connect them // get repository let photoRepository = connection.getRepository(Photo); // saving a photo also save the metadata await photoRepository.save(photo); console.log("Photo is saved, photo metadata is saved too.") }).catch(error =\> console.log(error));

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's side, the metadata would not be saved automatically.

Creating a many-to-one / one-to-many relation

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:

import {Entity, Column, PrimaryGeneratedColumn, OneToMany, JoinColumn} from "typeorm"; import {Photo} from "./Photo"; @Entity() export class Author { @PrimaryGeneratedColumn() id: number; @Column() name: string; @OneToMany(type =\> Photo, photo =\> photo.author) // note: we will create author property in the Photo class below photos: Photo[]; }
Author

contains an inverse side of a relation.

OneToMany

is always an inverse side of 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:

import {Entity, Column, PrimaryGeneratedColumn, ManyToOne} from "typeorm"; import {PhotoMetadata} from "./PhotoMetadata"; import {Author} from "./Author"; @Entity() export class Photo { /\* ... other columns \*/ @ManyToOne(type =\> Author, author =\> author.photos) author: Author; }

In many-to-one / one-to-many relation, 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:

+-------------+--------------+----------------------------+ | author | +-------------+--------------+----------------------------+ | id | int(11) | PRIMARY KEY AUTO\_INCREMENT | | name | varchar(255) | | +-------------+--------------+----------------------------+

It will also modify the

photo

table, adding a new

author

column and creating a foreign key for it:

+-------------+--------------+----------------------------+ | photo | +-------------+--------------+----------------------------+ | id | int(11) | PRIMARY KEY AUTO\_INCREMENT | | name | varchar(255) | | | description | varchar(255) | | | filename | varchar(255) | | | isPublished | boolean | | | authorId | int(11) | FOREIGN KEY | +-------------+--------------+----------------------------+

Creating a many-to-many relation

Let's create a many-to-one / 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:

import {Entity, PrimaryGeneratedColumn, Column, ManyToMany, JoinTable} from "typeorm"; @Entity() export class Album { @PrimaryGeneratedColumn() id: number; @Column() name: string; @ManyToMany(type =\> Photo, photo =\> photo.albums) @JoinTable() photos: Photo[]; }
@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:

export class Photo { /// ... other columns @ManyToMany(type =\> Album, album =\> album.photos) albums: Album[]; }

After you run the application, the ORM will create a album_photos_photo_albums junction table:

+-------------+--------------+----------------------------+ | album\_photos\_photo\_albums | +-------------+--------------+----------------------------+ | album\_id | int(11) | PRIMARY KEY FOREIGN KEY | | photo\_id | int(11) | PRIMARY KEY FOREIGN KEY | +-------------+--------------+----------------------------+

Don't forget to register the

Album

class with your connection in the ORM:

const options: ConnectionOptions = { // ... other options entities: [Photo, PhotoMetadata, Author, Album] };

Now let's insert albums and photos to our database:

let connection = await createConnection(options); // create a few albums let album1 = new Album(); album1.name = "Bears"; await connection.manager.save(album1); let album2 = new Album(); album2.name = "Me"; await connection.manager.save(album2); // create a few photos let photo = new Photo(); photo.name = "Me and Bears"; photo.description = "I am near polar bears"; photo.filename = "photo-with-bears.jpg"; photo.albums = [album1, album2]; await connection.manager.save(photo); // now our photo is saved and albums are attached to it // now lets load them: const loadedPhoto = await connection .getRepository(Photo) .findOne(1, { relations: ["albums"] });
loadedPhoto

will be equal to:

{ id: 1, name: "Me and Bears", description: "I am near polar bears", filename: "photo-with-bears.jpg", albums: [{ id: 1, name: "Bears" }, { id: 2, name: "Me" }] }

Using QueryBuilder

You can use QueryBuilder to build SQL queries of almost any complexity. For example, you can do this:

let photos = await connection .getRepository(Photo) .createQueryBuilder("photo") // first argument is an alias. Alias is what you are selecting - photos. You must specify it. .innerJoinAndSelect("photo.metadata", "metadata") .leftJoinAndSelect("photo.albums", "album") .where("photo.isPublished = true") .andWhere("(photo.name = :photoName OR photo.name = :bearName)") .orderBy("photo.id", "DESC") .skip(5) .take(10) .setParameters({ photoName: "My", bearName: "Mishka" }) .getMany();

This query selects all published photos with "My" or "Mishka" names. It will select results from position 5 (pagination offset), and will select only 10 results (pagination limit). The selection result will be ordered by id in descending order. The photo's albums will be left-joined and their metadata will be inner joined.

You'll use the query builder in your application a lot. Learn more about QueryBuilder here.

Samples

Take a look at the samples in sample for examples of usage.

There are a few repositories which you can clone and start with:

Extensions

There are several extensions that simplify working with TypeORM and integrating it with other modules:

Contributing

Learn about contribution here and how to setup your development environment here.

This project exists thanks to all the people who contribute:

Sponsors

Open source is hard and time-consuming. If you want to invest into TypeORM's future you can become a sponsor and make our core team to spend more time on TypeORM's improvements and new features. Become a sponsor

Gold Sponsors

Become a gold sponsor and get a premium technical support from our core contributors. Become a gold sponsor

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.