TypeORM Integration

Relevant source files

• integration/typeorm/ormconfig.json
• integration/typeorm/src/app.module.ts
• integration/typeorm/src/async-class-options.module.ts
• integration/typeorm/src/async-existing-options.module.ts
• integration/typeorm/src/async-options.module.ts
• integration/typeorm/src/database.module.ts
• sample/02-gateways/package.json
• sample/04-grpc/package.json
• sample/05-sql-typeorm/jest.json
• sample/05-sql-typeorm/package.json
• sample/05-sql-typeorm/src/app.module.ts
• sample/05-sql-typeorm/src/users/dto/create-user.dto.ts
• sample/05-sql-typeorm/src/users/user.entity.ts
• sample/05-sql-typeorm/src/users/users.controller.spec.ts
• sample/05-sql-typeorm/src/users/users.controller.ts
• sample/05-sql-typeorm/src/users/users.module.ts
• sample/05-sql-typeorm/src/users/users.service.spec.ts
• sample/05-sql-typeorm/src/users/users.service.ts
• sample/05-sql-typeorm/test/users/users.e2e-spec.ts
• sample/06-mongoose/package.json
• sample/07-sequelize/package.json
• sample/10-fastify/package.json
• sample/13-mongo-typeorm/package.json
• sample/13-mongo-typeorm/src/app.module.ts
• sample/14-mongoose-base/package.json
• sample/15-mvc/package.json
• sample/16-gateways-ws/package.json
• sample/17-mvc-fastify/package.json

Purpose and Scope

This document covers the integration of TypeORM with NestJS applications, focusing on the @nestjs/typeorm package and its configuration patterns for both SQL and NoSQL databases. TypeORM serves as NestJS's primary Object-Relational Mapping (ORM) solution, providing support for multiple database systems including MySQL, PostgreSQL, SQLite, and MongoDB.

For other database integration approaches, see Sequelize Integration for SQL-specific ORM patterns and Mongoose Integration for MongoDB-specific ODM patterns.

Architecture Overview

The NestJS TypeORM integration follows a modular architecture where the TypeOrmModule provides database connection management and entity repository injection into the dependency injection system.

Code-to-System Mapping: Repository Pattern

The following diagram bridges the natural language concept of "Repository Pattern" to the specific classes and functions used in the NestJS TypeORM integration.

Sources: sample/05-sql-typeorm/src/users/users.service.ts1-25 sample/05-sql-typeorm/src/users/users.service.spec.ts2-5

Implementation Flow

Sources: sample/05-sql-typeorm/src/app.module.ts1-20 sample/05-sql-typeorm/src/users/users.module.ts1-15 sample/05-sql-typeorm/package.json21-30 sample/13-mongo-typeorm/package.json21-30

Database Configuration Patterns

NestJS TypeORM integration supports multiple database configurations through the TypeOrmModule.forRoot() and TypeOrmModule.forRootAsync() methods.

SQL Database Configuration

SQL integrations typically require a driver like mysql2 and configuration for host, port, and credentials.

Sources: sample/05-sql-typeorm/src/app.module.ts8-18 sample/05-sql-typeorm/package.json26-30

NoSQL (MongoDB) Configuration

The MongoDB integration uses the mongodb driver. While it uses the same TypeOrmModule, the configuration properties shift to URI-based or MongoDB-specific options.

Sources: sample/13-mongo-typeorm/src/app.module.ts1-20 sample/13-mongo-typeorm/package.json21-31

Entity Definition and Repository Injection

Entities are defined using decorators like @Entity(), @PrimaryGeneratedColumn(), and @Column().

Entity Mapping Diagram

This diagram maps the code entities used in a typical TypeORM setup to their functional roles.

Sources: sample/05-sql-typeorm/src/users/user.entity.ts1-15

Repository Injection Pattern

The @InjectRepository() decorator is used to inject the Repository instance for a specific entity into a service.

Sources: sample/05-sql-typeorm/src/users/users.service.ts10-14

Module Registration Patterns

TypeORM modules support both synchronous and asynchronous registration.

Feature Module Integration

Feature modules use TypeOrmModule.forFeature() to register entities within the current scope. This makes the repositories available for injection in the module's providers.

Sources: sample/05-sql-typeorm/src/users/users.module.ts1-12

Testing Configuration

Testing TypeORM integrations involves mocking the repository or using a specialized testing module. The getRepositoryToken() function is critical for providing mock implementations in unit tests.

Mocking Repositories in Unit Tests

In unit tests, the repository is often replaced with a mock object using the token generated by getRepositoryToken(Entity).

Sources: sample/05-sql-typeorm/src/users/users.service.spec.ts28-42

Package Dependencies

The TypeORM integration requires specific package configurations depending on the database.

SQL Database Dependencies (MySQL Example)

Package	Version	Purpose
@nestjs/typeorm	11.0.3	NestJS TypeORM integration
typeorm	1.1.0	Core TypeORM library
mysql2	3.23.1	MySQL database driver

Sources: sample/05-sql-typeorm/package.json25-30

MongoDB Dependencies

Package	Version	Purpose
@nestjs/typeorm	11.0.3	NestJS TypeORM integration
typeorm	1.1.0	Core TypeORM library
mongodb	7.5.0	MongoDB database driver

Sources: sample/13-mongo-typeorm/package.json25-30