Data Overview & TypeORM

Entities are classes decorated with @Entity(). Relations are declared with @OneToOne(), @OneToMany() / @ManyToOne() and @ManyToMany(). The Bookshelf entities:

User is the same shape (id, a unique email column and a @OneToMany to Review).

Three details matter in a modern ESM project. First, Author and Book import each other, and with emitDecoratorMetadata the compiler emits a runtime reference to the property type. Compiled with tsc and run as ESM without the wrapper, the application fails at start with ReferenceError: Cannot access 'Book' before initialization. Wrapping relation property types in TypeORM’s Relation<T> (imported as a type) avoids emitting that reference, and the application then boots; the arrow function in @ManyToOne(() ⇒ Author, …​) defers the real class lookup. Second, the relation owner (the many side, Book.author) holds the foreign key; @JoinColumn({ name: 'author_id' }) chooses its column name, and without it TypeORM names the column from the property (bookId, userId on Review above). Third, foreignKeyConstraintName gives each foreign key a readable, fixed name. TypeORM compares constraint names when it generates migrations: without it, TypeORM expects hashed names such as FK_24b753b0490a992a6941451f405, and a hand-written migration that names the constraint FK_book_author makes migration:generate emit a drop-and-recreate of every foreign key.

@PrimaryGeneratedColumn() uses the increment strategy, which TypeORM maps to SERIAL on PostgreSQL. @PrimaryGeneratedColumn('identity') maps to the SQL-standard integer GENERATED BY DEFAULT AS IDENTITY, which the PostgreSQL documentation prefers for new tables; with TypeORM 1.1 the better-sqlite3 driver does not read the generated key back for that strategy (a saved Author keeps id undefined, so inserting its Book fails with NOT NULL constraint failed: book.author_id). The page keeps increment so the same entities also run on the SQLite test variant; if PostgreSQL is your only engine, prefer identity.

Relations are not loaded unless you ask for them. In the service below, relations: { author: true, reviews: true } joins them in; a plain findOne would return a Book with no author property.

Source: NestJS documentation: TypeORM, "Relations" and TypeORM documentation: Relations.

TypeOrmModule.forRoot() registers the connection once, normally in the root module. It accepts every property of the TypeORM DataSource constructor plus a few Nest-specific ones:

Real applications take connection details from configuration, so use forRootAsync(). The factory behaves like any asynchronous provider: it can be async and can inject other providers, here the ConfigService from @nestjs/config. This is the module used by the examples; it connects to PostgreSQL with the host, port, user, password and database name taken from configuration (DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, DB_NAME), and getOrThrow() stops the boot if one of the required values is missing.

Environment variables are strings, hence the Number(…​) around the port. A single connection URL works as well: replace the five connection properties with url: config.getOrThrow<string>('DATABASE_URL'), as the multiple-data-source example further down does. Started against an empty PostgreSQL database, the application applies the initial migration, and printing dataSource.options.synchronize and the names of dataSource.entityMetadatas shows synchronize off and the four entities discovered through autoLoadEntities:

This variant needs npm install --save-dev better-sqlite3 and no database server, which makes it handy for a quick demo or a fast test. It cannot apply the initial migration, because that migration is written in PostgreSQL DDL, so it lets synchronize create the schema; that is acceptable only because the database disappears with the process. The services, controller, transactions and pagination of this page behave the same on it, apart from the generated ids noted in the transactions section. It is not a substitute for testing against PostgreSQL (see the testing section).

forRootAsync() also accepts useClass (a class implementing TypeOrmOptionsFactory and its createTypeOrmOptions() method) and useExisting (reuse a provider from an imported module). The name of a data source must be set outside useFactory, at the same level as useFactory, useClass or useExisting; otherwise Nest cannot register the data source under the right token. A dataSourceFactory function can be supplied alongside any of them to build the DataSource yourself; it receives the resolved options and returns a promise of a DataSource, which TypeOrmModule initialises if it is not initialised yet.

autoLoadEntities keeps the root module from importing every entity, which would break domain boundaries. It only picks up entities registered through forFeature(). An entity that is referenced only from a relation of another entity, and is never passed to any forFeature(), is not loaded.

Source: NestJS documentation: TypeORM, "Auto-load entities" and Async configuration.

TypeOrmModule.forFeature([…​]) registers the repositories of the listed entities in the current module scope. You then inject a Repository<T> with @InjectRepository(Entity). The DataSource and EntityManager of the default connection are available everywhere without importing anything, and @InjectDataSource() injects the data source explicitly.

A controller that exposes the service returns the entity graph directly. With one review saved, GET /books/1 returns the following on PostgreSQL (the author has id 2 because the rolled-back transaction in the next section consumed id 1):

Returning entities straight to the client couples the API to the table layout; serialization and DTOs are the usual remedy, and the OpenAPI and GraphQL pages build on that.

Repositories are only injectable where forFeature() was imported. To use Book’s repository from another module, re-export the generated providers by exporting the module (`exports: [TypeOrmModule], as the module above does), then import that module where it is needed. Forgetting this produces a Nest can’t resolve dependencies of …​ BookRepository error at boot.

Source: NestJS documentation: TypeORM, "Repository pattern".

A transaction groups several statements into one atomic unit; see Transaction Control for isolation levels and locking in SQL terms. The Nest documentation recommends the QueryRunner class because it gives full control: you connect, start the transaction, do the work on queryRunner.manager, then commit or roll back, and always release the runner.

A call that throws after saving the author leaves no author row behind (countAuthors() returns 0), while a successful call commits both rows (1). On PostgreSQL the rolled-back insert still consumes a value of the author sequence, because sequences are not transactional, so the next author receives id 2; never assume generated ids are gap-free. (The SQLite variant reuses the id, which is one of the ways it hides PostgreSQL behaviour.) Note the throw err in the catch block: the example in the Nest documentation rolls back and swallows the error, which hides failures from the caller. A manually created query runner must be released, otherwise its connection leaks from the pool.

The callback style, dataSource.transaction(async (manager) ⇒ { …​ }), commits when the callback returns and rolls back when it throws. It is shorter, and appropriate when the whole unit of work fits in one function:

Restocking book 1 by 5 returns a stock of 5; restocking a missing book throws Book 999 not found and the NotFoundException becomes a 404 response through the exception filter layer. Two pitfalls: only use the manager passed to the callback (or queryRunner.manager) inside the transaction, since the injected repositories run on other pooled connections and are outside it; and a transaction spanning a repository call that was injected into another service needs that service to accept the EntityManager, which is why many teams pass manager explicitly or use a request-scoped context library. The Nest documentation also suggests a small factory class for creating query runners, so unit tests mock one narrow interface instead of the whole DataSource.

Source: NestJS documentation: TypeORM, "TypeORM Transactions" and TypeORM documentation: Transactions.

Listing endpoints should never return an unbounded table. TypeORM offers offset pagination through skip/take and findAndCount(), which also returns the total number of rows. Always add a deterministic order; without it two pages can overlap or skip rows. Offset pagination degrades on deep pages and misbehaves when rows are inserted between requests; keyset (cursor) pagination, which filters on the last seen key, avoids both. The Pagination: Offset vs. Keyset page covers the trade-offs; here are both in TypeORM.

With five books in the table, GET /books?page=2&pageSize=2 returns the third and fourth rows and a total of five; the keyset calls return cursors 2, 4 and null (the last page holds one item). The author ids are one ahead of the book ids because of the rolled-back transaction above. In the controller, ParseIntPipe({ optional: true }) parses the query values; see pipes and validation.

Source: TypeORM documentation: Find options (pagination is not covered on the Nest data pages; the Nest documentation only shows the repository pattern).

A subscriber listens to entity lifecycle events such as beforeInsert or afterInsert. In Nest the subscriber is a normal provider, so it can inject services: register it in the module’s providers and have it add itself to the data source. The Nest documentation shows the constructor taking a DataSource and calling dataSource.subscribers.push(this). The version below adds @Injectable() and @InjectDataSource() to make the dependency explicit and to name which data source it belongs to; the documentation form (a plain DataSource constructor parameter) works too.

After the transaction example creates "The Dispossessed", the subscriber has recorded ["The Dispossessed"]. Event subscribers cannot be request-scoped; see injection scopes. Subscriber events fire for operations that go through the entity manager or repository (save, insert and so on); raw SQL through query() bypasses them. Keep subscribers small: they run inside the persistence call, so slow or failing work there slows or fails the write (and, in a transaction, may roll it back). For side effects like sending an e-mail, prefer emitting an event after commit.

Source: NestJS documentation: TypeORM, "Subscribers".

synchronize: true makes TypeORM alter the schema to match the entities on every start. The Nest documentation warns not to use it in production because you can lose production data, for example when a renamed column is treated as a drop plus an add. The supported way to evolve a schema is migrations: versioned classes that move the schema up (and back down) while preserving data. Migrations are executed in order and recorded in a migrations table, so each runs once. The general discipline (expand/contract, backward-compatible steps, rollbacks) is covered in Evolving the Database Model.

A migration implements MigrationInterface with up() and down(). This is the first migration of the example, written in PostgreSQL DDL. Its column types, defaults and constraint names match the entities exactly, so that migration:generate finds no difference after it has run:

Two ways to run migrations:

The CLI does not run Nest, so there is no ConfigService here: the file reads the same variables straight from process.env. Export them in the shell (or in CI) before calling the CLI.

In an ESM project the CLI needs compiled JavaScript, so compile first and point -d at the output. Here tsconfig.typeorm-cli.json is a small tsconfig that extends the main one and compiles only the entity, migration and data-source files to dist-typeorm/:

On an empty database, migration:show lists [ ] InitialSchema1700000000000; migration:run reports Migration InitialSchema1700000000000 has been executed successfully and migration:show then lists [X] 1 InitialSchema1700000000000. Straight after that, migration:generate reports No changes in database schema were found, which confirms that the hand-written migration matches the entities. After adding a nullable isbn column to Book (@Column({ type: 'varchar', length: 13, nullable: true })), it writes a new timestamped file whose up() runs ALTER TABLE "book" ADD "isbn" character varying(13) and whose down() drops the column. migration:revert reverts the last executed migration. Adapt the paths to your build output.

Always review generated SQL: on PostgreSQL a rename can be generated as drop plus add, and mismatched constraint names produce drop-and-recreate statements (see the entities section). In CI, run the migrations against a throwaway PostgreSQL database, the same engine as production; a database created by synchronize on SQLite proves nothing about the migration.

Source: NestJS documentation: TypeORM, "Migrations" and TypeORM documentation: Migrations.

A second database needs a second forRoot() registration with a unique name. The unnamed registration is the default one; two registrations without names, or with the same name, override each other (Nest logs a warning when it detects this, and the same warning appears if one process creates several Nest applications with a default data source, for instance in a test file that bootstraps two modules).

Each registration points at its own PostgreSQL database through a connection URL (DATABASE_URL and REPORTS_DATABASE_URL), and each applies the migrations to its own database. app.get(DataSource) and app.get(getDataSourceToken('reports')) are different objects, @InjectDataSource('reports') and @InjectEntityManager('reports') resolve to the named one, and writing a Review into the named source leaves the default source’s book table at 0 rows while the named one’s review table holds 1. Each forRootAsync() lists imports: [ConfigModule]; without it, or a global ConfigModule, Nest cannot resolve ConfigService inside TypeOrmCoreModule and the boot fails. forFeature() and @InjectRepository() both take the data source name as their second argument and fall back to default when it is omitted. To inject a named data source into a factory provider, use getDataSourceToken('reports'). With forRootAsync() the name must sit next to useFactory, as described above.

Source: NestJS documentation: TypeORM, "Multiple databases".

Unit tests should not need a database. Each registered repository has an injection token, which getRepositoryToken(Entity) returns (for the default source it is the string BookRepository; for a named source the name is prefixed, for example reports_BookRepository). Provide a mock under that token with a custom provider and the service under test receives it where it asks for @InjectRepository(Book). The same works for the data source with getDataSourceToken(), which returns the DataSource class itself for the default source.

The test runs under Vitest; under Jest use jest.fn() instead of vi.fn(). Mocks prove your service calls the repository correctly, not that a query is valid; for that, an integration test against a real PostgreSQL database (a container) is worth the time. The in-memory SQLite variant is a compromise that hides PostgreSQL-specific behaviour such as JSON operators, locking, non-transactional sequences and the PostgreSQL DDL of the migrations, which it cannot run at all. The broader testing toolbox is on the Testing page.

Source: NestJS documentation: TypeORM, "Testing" and Testing.