nestjs-boost 0.0.0-stage → 1.2.0

package/skills/nestjs-database-mikro-orm/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: nestjs-database-mikro-orm
+description: Integrates MikroORM v7 with NestJS 12 through @mikro-orm/nestjs — MikroOrmModule.forRoot/forRootAsync (driver beside useFactory), legacy decorators from @mikro-orm/decorators/legacy with ReflectMetadataProvider, entities and Rel relation wrappers, forFeature repositories and custom repositories, autoLoadEntities, the per-request EntityManager context middleware, @CreateRequestContext for queues and cron jobs, em.transactional and @Transactional, MikroORM serialization instead of ClassSerializerInterceptor, multiple contexts, shutdown hooks, and test mocks with getRepositoryToken. Use when the project uses or wants MikroORM, when adding entities, repositories, flush/transactions, or when the global EntityManager throws a ValidationError outside a request context, missing decorator exports after upgrading to v7, or broken relation JSON. Not for TypeORM, Drizzle, Prisma, Mongoose or Sequelize (their own skills).
+compatibility: NestJS 12.x; MikroORM v7, @mikro-orm/nestjs v7 (third-party, maintained by the MikroORM team), a @mikro-orm driver package
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS + MikroORM v7
+
+```bash
+npm i @mikro-orm/nestjs @mikro-orm/core @mikro-orm/decorators @mikro-orm/postgresql   # or sqlite, mysql, mongodb…
+```
+
+`@mikro-orm/nestjs` is maintained by the MikroORM team. v7 changes: decorators moved to `@mikro-orm/decorators/legacy`, `ReflectMetadataProvider` is no longer the default, and `forRoot()` needs an explicit config.
+
+## Configuration
+
+```typescript
+// mikro-orm.config.ts — shared with the MikroORM CLI
+import { ReflectMetadataProvider } from '@mikro-orm/decorators/legacy';
+import { defineConfig } from '@mikro-orm/postgresql';
+export default defineConfig({
+  clientUrl: process.env.DATABASE_URL,
+  entities: ['./dist/**/*.entity.js'],
+  entitiesTs: ['./src/**/*.entity.ts'],
+  metadataProvider: ReflectMetadataProvider,       // required with legacy decorators
+});
+
+// app.module.ts — async variant
+MikroOrmModule.forRootAsync({
+  driver: PostgreSqlDriver,                        // beside useFactory, not inside: registers driver-specific tokens
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({ clientUrl: config.getOrThrow('DATABASE_URL'), autoLoadEntities: true, metadataProvider: ReflectMetadataProvider }),
+}),
+```
+
+- Nest-specific options: `autoLoadEntities`, `registerRequestContext` (true), `forRoutesPath`, `scope`, `contextName`.
+- Inject `MikroORM` and `EntityManager` from **your driver package** (`@mikro-orm/postgresql`) for the driver-specific API.
+- `autoLoadEntities` skips relation-only entities and doesn't affect the CLI (keep globs there). Base entities go in config, not `forFeature()`.
+- Call `app.enableShutdownHooks()` so the ORM closes on SIGTERM.
+
+## Entities and repositories
+
+```typescript
+@Entity({ repository: () => BookRepository })
+export class Book {
+  [EntityRepositoryType]?: BookRepository;
+  @PrimaryKey() id: number;
+  @Property() title: string;
+  @ManyToOne(() => Author) author: Rel<Author>;                 // Rel<T>/Ref<T> avoids circular metadata at runtime
+  @Property({ hidden: true }) internalNote?: string;            // excluded from JSON
+}
+
+export class BookRepository extends EntityRepository<Book> {
+  findByTitle(title: string) { return this.findOne({ title }); }
+}
+
+@Module({ imports: [MikroOrmModule.forFeature([Book])], providers: [BooksService] })
+export class BooksModule {}
+
+@Injectable()
+export class BooksService {
+  constructor(private readonly books: BookRepository, private readonly em: EntityManager) {}   // custom repo injected by class
+  async create(title: string, authorId: number) {
+    const book = this.em.create(Book, { title, author: authorId });
+    await this.em.flush();                                      // repositories have no persist/flush
+    return book;
+  }
+}
+```
+
+Default repositories: `@InjectRepository(Photo) repo: EntityRepository<Photo>`.
+
+## Request context (identity map per request)
+
+- HTTP requests get a forked `EntityManager` from the module's middleware automatically.
+- Outside HTTP (queue processors, `@Cron`, event listeners, microservice handlers) the global EM throws a `ValidationError` for `find()`/`flush()`. Decorate the method with `@CreateRequestContext()` (directly above the method, **below** `@Cron()`/`@Process()` etc.); the class needs an `orm` or `em` property. `@EnsureRequestContext()` reuses an existing context.
+- Alternative: `registerRequestContext: false, scope: Scope.REQUEST` — makes every EM consumer request-scoped (slower).
+
+## Transactions
+
+- `em.flush()` already wraps queued writes in one transaction.
+- Explicit: `await this.em.transactional(async (em) => { em.create(Photo, { name }); })` (forked EM; flushed and committed when the callback resolves; nested calls use savepoints).
+- Decorator: `@Transactional()` on an async method of a class with `em`/`orm`.
+
+## Serialization
+
+Don't use `ClassSerializerInterceptor` (class-transformer) with MikroORM entities: it mangles relation wrappers. Use entity options (`hidden: true`, `persist: false`, serializers), `serialize(entity, { populate, exclude, fields, groups })`, or `wrap(entity).toObject()`.
+
+## Multiple databases
+
+One `forRoot()` per database with a unique `contextName` and `registerRequestContext: false` on each (with `forRootAsync`, `contextName` beside `useFactory`). Then `forFeature([Album], 'albums')`, `@InjectRepository(Album, 'albums')`, `@InjectEntityManager('albums')`, `@InjectMikroORM('albums')`, `@InjectMikroORMs()`.
+
+## Testing
+
+`{ provide: getRepositoryToken(Photo), useValue: mockRepo }` (or the custom repository class as token) and `{ provide: EntityManager, useValue: mockEm }`. For multiple contexts: `getRepositoryToken(Album, 'albums')`.
+
+## Workflow
+
+- [ ] 1. Install core, decorators, driver and `@mikro-orm/nestjs`; write `mikro-orm.config.ts` with `ReflectMetadataProvider`.
+- [ ] 2. Register `forRoot(config)` or `forRootAsync({ driver, useFactory })`; enable shutdown hooks.
+- [ ] 3. Entities with legacy decorators and `Rel<T>`; `forFeature` per module; writes through `em` + `flush`.
+- [ ] 4. Add `@CreateRequestContext()` to every non-HTTP entry point that touches the EM.
+- [ ] 5. Migrations via the MikroORM CLI using the same config. Build, lint, run tests, start the app.
+
+Sources: [MikroORM](https://docs.nestjs.com/data/mikroorm)

package/skills/nestjs-database-mongoose/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: nestjs-database-mongoose
+description: Integrates MongoDB with NestJS 12 through @nestjs/mongoose — MongooseModule.forRoot/forRootAsync, decorator schemas with @Schema/@Prop/SchemaFactory and HydratedDocument types, references and typed populate, raw() nested objects, subdocuments and DocumentArray types, @Virtual properties, forFeature models injected with @InjectModel, hooks and plugins via forFeatureAsync or connectionFactory, discriminators, transactions with connection.startSession(), multiple named connections, connection events with onConnectionCreate, and mocking models with getModelToken. Use when the project uses or wants MongoDB/Mongoose, when adding a schema, model, populate, middleware hook or transaction, or when seeing model injection errors. Not for SQL ORMs (TypeORM, Drizzle, Prisma, MikroORM, Sequelize skills) or MongoDB via TypeORM (nestjs-database-typeorm).
+compatibility: NestJS 12.x; @nestjs/mongoose, mongoose
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS + Mongoose
+
+```bash
+npm i @nestjs/mongoose mongoose
+```
+
+## Setup
+
+```typescript
+// app.module.ts
+MongooseModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    uri: config.getOrThrow<string>('MONGODB_URI'),
+    onConnectionCreate: (connection: Connection) => {
+      connection.on('disconnected', () => logger.warn('MongoDB disconnected'));
+      return connection;
+    },
+  }),
+}),
+```
+
+`forRoot(uri, options)` takes `mongoose.connect()` options plus Nest extras (`connectionName`, `connectionFactory`, `onConnectionCreate`).
+
+## Schema → model → service
+
+```typescript
+// cats/schemas/cat.schema.ts
+export type CatDocument = HydratedDocument<Cat>;
+
+@Schema({ timestamps: true })                                   // collection: "cats"
+export class Cat {
+  @Prop({ required: true }) name: string;
+  @Prop() age: number;
+  @Prop([String]) tags: string[];
+  @Prop({ type: mongoose.Schema.Types.ObjectId, ref: 'Owner' }) owner: mongoose.Types.ObjectId;   // not always populated
+  @Prop(raw({ firstName: { type: String }, lastName: { type: String } })) details: Record<string, any>;
+  @Virtual({ get: function (this: Cat) { return `${this.name} (${this.age})`; } }) label: string;
+}
+export const CatSchema = SchemaFactory.createForClass(Cat);
+
+// cats/cats.module.ts
+@Module({ imports: [MongooseModule.forFeature([{ name: Cat.name, schema: CatSchema }])], providers: [CatsService] })
+export class CatsModule {}
+
+// cats/cats.service.ts
+@Injectable()
+export class CatsService {
+  constructor(@InjectModel(Cat.name) private readonly catModel: Model<Cat>) {}
+  create(dto: CreateCatDto) { return new this.catModel(dto).save(); }
+  findAll() { return this.catModel.find().lean().exec(); }
+  findWithOwner(id: string) { return this.catModel.findById(id).populate<{ owner: Owner }>('owner').exec(); }
+}
+```
+
+- Keep schemas next to their domain module. To share a model, export `MongooseModule` from the owning module (or export a service).
+- Type references as `ObjectId` unless always populated, then populate with an explicit generic.
+- Subdocuments: `@Prop(NameSchema) name: Name` with `HydratedDocument<Person, { name: Types.Subdocument<Types.ObjectId> & Name }>`; arrays: `@Prop([NameSchema])` with `Types.DocumentArray<Name>`.
+- Validate request input with DTOs/schemas (nestjs-validation-serialization) — Mongoose validation is a second line, not the API contract. Validate id parameters (e.g. a 24-hex-character rule in your schema/DTO) before querying, so malformed ids get a 400 instead of a Mongoose `CastError` 500.
+
+## Hooks, plugins, discriminators
+
+```typescript
+MongooseModule.forFeatureAsync([{
+  name: Cat.name,
+  imports: [ConfigModule], inject: [ConfigService],
+  useFactory: (config: ConfigService) => {
+    const schema = CatSchema;
+    schema.pre('save', function () { /* … */ });
+    schema.plugin(autopopulate);
+    return schema;
+  },
+}]),
+```
+
+- Global plugins: `forRoot(uri, { connectionFactory: (conn) => { conn.plugin(p); return conn; } })` (before models are created).
+- Discriminators: base schema with `discriminatorKey: 'kind'`, then `forFeature([{ name: Event.name, schema: EventSchema, discriminators: [{ name: SignUpEvent.name, schema: SignUpEventSchema }] }])`.
+- `DefinitionsFactory.createForClass(Cat)` gives a raw definition to tweak by hand.
+
+## Transactions
+
+```typescript
+constructor(@InjectConnection() private readonly connection: Connection) {}
+
+async transfer() {
+  const session = await this.connection.startSession();
+  try {
+    await session.withTransaction(async () => {
+      await this.accounts.updateOne({ _id: a }, { $inc: { balance: -10 } }, { session });
+      await this.accounts.updateOne({ _id: b }, { $inc: { balance: 10 } }, { session });
+    });
+  } finally { await session.endSession(); }
+}
+```
+
+Start sessions from the injected connection, not `mongoose.startSession()`. Transactions need a replica set (or Atlas).
+
+## Multiple connections
+
+`forRoot(uri, { connectionName: 'cats' })` (names are mandatory with several connections), `forFeature([...], 'cats')`, `@InjectModel(Cat.name, 'cats')`, `@InjectConnection('cats')`, `getConnectionToken('cats')`, `getModelToken(Cat.name, 'cats')`.
+
+## Testing
+
+Unit: `{ provide: getModelToken(Cat.name), useValue: { find: vi.fn().mockReturnValue({ exec: vi.fn() }) } }`. Integration: `mongodb-memory-server` or a Testcontainers MongoDB (replica set if you use transactions).
+
+## Workflow
+
+- [ ] 1. Install; `forRootAsync` from validated config.
+- [ ] 2. Schema class + `SchemaFactory`; `forFeature` in the feature module; inject the model.
+- [ ] 3. Add indexes (`@Prop({ index: true })` / `schema.index()`), hooks, discriminators as needed.
+- [ ] 4. Tests with `getModelToken` mocks; e2e against a real/in-memory MongoDB.
+- [ ] 5. Build, lint, run tests, start the app.
+
+Sources: [MongoDB](https://docs.nestjs.com/data/mongodb)

package/skills/nestjs-database-prisma/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: nestjs-database-prisma
+description: Integrates Prisma ORM 7 with NestJS 12 — installing prisma@7 with a driver adapter (better-sqlite3, pg, mariadb, mssql), prisma init with a generated client inside src, ESM vs CJS moduleFormat, schema models and prisma migrate dev, prisma generate in CI, a PrismaService extending PrismaClient with the adapter and $connect/$disconnect lifecycle hooks, a PrismaModule, typed CRUD services with generated Prisma types, sequential and interactive $transaction, and mocking PrismaService in tests. Use when the project uses or wants Prisma, when adding a model, migration, query or transaction with Prisma, or when hitting Prisma 7 setup errors (missing adapter, wrong prisma CLI version, generated client not found, import.meta in CommonJS, beforeExit hooks). Not for TypeORM, Drizzle, Mongoose, MikroORM or Sequelize (their own skills).
+compatibility: NestJS 12.x; prisma@7 and @prisma/client@7 with an @prisma/adapter-* package; @nestjs/config
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS + Prisma 7
+
+Prisma has no Nest package: you wrap the generated client in a provider.
+
+## Install (pin Prisma 7)
+
+```bash
+npm i -D prisma@7 dotenv
+npm i @prisma/client@7 @prisma/adapter-pg          # or adapter-better-sqlite3 | adapter-mariadb | adapter-mssql
+npx prisma init --datasource-provider postgresql --output ../src/generated/prisma
+```
+
+- **Install `prisma@7` explicitly**: `latest` may point at a Prisma 8 pre-release without `migrate`/`generate`.
+- `init` creates `prisma/schema.prisma`, the Prisma config file in the project root (`prisma7.config.ts`; `prisma.config.ts` before 7.10) and `.env`, and git-ignores the generated client.
+- The client is generated into `src/generated/prisma` and compiled with the app. ESM projects (the v12 default) need nothing else; CommonJS projects set `moduleFormat = "cjs"` in the generator (the ESM client uses `import.meta`).
+- The connection URL lives in `DATABASE_URL`, read by the Prisma config file; the app reads it through `ConfigService` (`ConfigModule.forRoot({ isGlobal: true })`).
+
+## Models and migrations
+
+```groovy
+generator client {
+  provider = "prisma-client"
+  output   = "../src/generated/prisma"
+}
+datasource db { provider = "postgresql" }
+
+model User {
+  id    Int    @id @default(autoincrement())
+  email String @unique
+  posts Post[]
+}
+model Post {
+  id       Int   @id @default(autoincrement())
+  title    String
+  author   User? @relation(fields: [authorId], references: [id])
+  authorId Int?
+}
+```
+
+- `npx prisma migrate dev --name init` creates and applies SQL migrations (development). Deploy with `npx prisma migrate deploy` in the release step.
+- `npx prisma generate` after every schema change — `migrate dev` doesn't run it — and **in CI/fresh checkouts before `nest build`**, since the client isn't committed. Add it to a `prebuild` script.
+
+## PrismaService and PrismaModule
+
+```typescript
+// src/prisma/prisma.service.ts
+import { PrismaPg } from '@prisma/adapter-pg';
+import { PrismaClient } from '../generated/prisma/client.js';
+
+@Injectable()
+export class PrismaService extends PrismaClient implements OnModuleInit, OnModuleDestroy {
+  constructor(config: ConfigService) {
+    super({ adapter: new PrismaPg({ connectionString: config.getOrThrow<string>('DATABASE_URL') }) });   // adapter is required in v7
+  }
+  async onModuleInit() { await this.$connect(); }        // fail at startup, not on first request
+  async onModuleDestroy() { await this.$disconnect(); }  // also closes the adapter's pool
+}
+
+// src/prisma/prisma.module.ts
+@Module({ providers: [PrismaService], exports: [PrismaService] })
+export class PrismaModule {}
+```
+
+- Call `app.enableShutdownHooks()` in `main.ts`; Prisma 7 has no `$on('beforeExit')`.
+- Import `PrismaModule` where needed, or mark it `@Global()` if nearly every module uses it.
+
+## Queries and transactions
+
+```typescript
+import { Prisma, User } from '../generated/prisma/client.js';
+
+@Injectable()
+export class UsersService {
+  constructor(private readonly prisma: PrismaService) {}
+  user(where: Prisma.UserWhereUniqueInput): Promise<User | null> { return this.prisma.user.findUnique({ where }); }
+
+  async page(skip: number, take: number) {
+    const [posts, total] = await this.prisma.$transaction([                // sequential, one transaction
+      this.prisma.post.findMany({ skip, take }), this.prisma.post.count(),
+    ]);
+    return { posts, total };
+  }
+  deleteWithPosts(id: number) {
+    return this.prisma.$transaction(async (tx) => {                       // interactive: use tx for every query
+      await tx.post.deleteMany({ where: { authorId: id } });
+      return tx.user.delete({ where: { id } });
+    });
+  }
+}
+```
+
+- Nested writes are transactional automatically. `$transaction(…, { maxWait, timeout, isolationLevel })`.
+- Generated types are compile-time only: validate request bodies with DTOs or schemas (nestjs-validation-serialization), not Prisma types.
+- Map known errors (unique violation `P2002`, not found `P2025`) to HTTP exceptions in the service or an exception filter.
+- Decorator-based transactions across services: `nestjs-cls` transactional plugin with the Prisma adapter.
+- Packages with stores (`@nestjs/outbox`, `@nestjs/webhooks`) use `fromPrisma(prisma)` and need the driver adapter client.
+
+## Testing
+
+```typescript
+const moduleRef = await Test.createTestingModule({
+  providers: [UsersService, { provide: PrismaService, useValue: { user: { findUnique: vi.fn() } } }],
+}).compile();
+```
+
+The mock replaces the class, so `onModuleInit` never connects. For module-level tests use `.overrideProvider(PrismaService)`. Run integration tests against a real database with `prisma migrate deploy` applied.
+
+## Workflow
+
+- [ ] 1. Install pinned Prisma 7 + adapter; `prisma init` with `--output ../src/generated/prisma`.
+- [ ] 2. Write models; `prisma migrate dev`; `prisma generate`; add `prisma generate` to the build pipeline.
+- [ ] 3. Add `PrismaService` (adapter + lifecycle) and `PrismaModule`; `enableShutdownHooks()`.
+- [ ] 4. Services with generated types; transactions via `$transaction`.
+- [ ] 5. Tests with a `PrismaService` mock. Build, lint, run tests, start the app.
+
+Sources: [Prisma](https://docs.nestjs.com/data/prisma)

package/skills/nestjs-database-sequelize/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: nestjs-database-sequelize
+description: Integrates Sequelize with NestJS 12 through @nestjs/sequelize and sequelize-typescript — SequelizeModule.forRoot/forRootAsync, Active Record models with @Table/@Column extending Model, associations (@HasMany, @BelongsTo, @BelongsToMany), forFeature with @InjectModel(User) typed as typeof User, autoLoadModels and synchronize, managed transactions with sequelize.transaction(), migrations with the Sequelize CLI, multiple named connections, connection retries and mocking models with getModelToken. Use when the project uses or wants Sequelize, when adding a model, association, transaction or migration, or when models aren't registered or injected. Not for TypeORM, Drizzle, Prisma, Mongoose or MikroORM (their own skills).
+compatibility: NestJS 12.x; @nestjs/sequelize, sequelize, sequelize-typescript, a dialect driver (mysql2, pg, …)
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS + Sequelize
+
+```bash
+npm i @nestjs/sequelize sequelize sequelize-typescript pg     # or mysql2, …
+npm i -D @types/sequelize
+```
+
+## Setup
+
+```typescript
+SequelizeModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    dialect: 'postgres',
+    uri: config.getOrThrow<string>('DATABASE_URL'),
+    autoLoadModels: true,          // models registered with forFeature()
+    synchronize: false,            // default true with autoLoadModels — turn off outside throwaway dev databases
+  }),
+}),
+```
+
+Extra options beside the Sequelize constructor's: `retryAttempts` (10), `retryDelay` (3000), `autoLoadModels` (false), `autoCloseConnection` (true), `synchronize` (true). Inject `Sequelize` (from `sequelize-typescript`) anywhere.
+
+## Models (Active Record)
+
+```typescript
+@Table
+export class User extends Model {
+  @Column firstName: string;
+  @Column({ defaultValue: true }) isActive: boolean;
+  @HasMany(() => Photo) photos: Photo[];
+}
+
+@Module({ imports: [SequelizeModule.forFeature([User])], providers: [UsersService] })
+export class UsersModule {}
+
+@Injectable()
+export class UsersService {
+  constructor(@InjectModel(User) private readonly userModel: typeof User) {}
+  findOne(id: string) { return this.userModel.findOne({ where: { id }, include: [Photo] }); }
+}
+```
+
+- Keep models in their domain module. To use a model in another module, export `SequelizeModule` from the owning module.
+- `autoLoadModels` skips models only referenced through associations: register every model via `forFeature()` (or list them in `models`).
+
+## Transactions (managed)
+
+```typescript
+await this.sequelize.transaction(async (t) => {
+  const opts = { transaction: t };
+  await this.userModel.create({ firstName: 'Ada' }, opts);
+  await this.photoModel.create({ userId: 1 }, opts);
+});   // commits when the callback resolves, rolls back on throw
+```
+
+Pass `{ transaction: t }` to every call. For testability, hide `sequelize.transaction` behind a small injectable factory instead of mocking `Sequelize`.
+
+## Migrations
+
+Sequelize CLI migrations live outside the Nest app (no DI). Use them instead of `synchronize` for anything with data you care about; keep CLI config reading the same env vars.
+
+## Multiple databases
+
+Name every non-default connection (`name: 'albumsConnection'`, beside `useFactory` for async), then `forFeature([Album], 'albumsConnection')`, `@InjectModel(Album, 'albumsConnection')`, `@InjectConnection('albumsConnection')`, `getConnectionToken('albumsConnection')`. Unnamed connections override each other.
+
+## Testing
+
+`{ provide: getModelToken(User), useValue: { findAll: vi.fn(), findOne: vi.fn() } }`.
+
+## Workflow
+
+- [ ] 1. Install; `forRootAsync` from validated config; decide `synchronize: false` + CLI migrations.
+- [ ] 2. Model class with decorators; `forFeature` in its module; `@InjectModel(Model)` typed `typeof Model`.
+- [ ] 3. Wrap multi-step writes in `sequelize.transaction`.
+- [ ] 4. Tests with `getModelToken` mocks. Build, lint, run tests, start the app.
+
+Sources: [Sequelize](https://docs.nestjs.com/data/sequelize)

package/skills/nestjs-database-typeorm/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: nestjs-database-typeorm
+description: Integrates TypeORM with NestJS 12 through @nestjs/typeorm — TypeOrmModule.forRoot/forRootAsync with ConfigService, entities and relations, autoLoadEntities, forFeature repositories with @InjectRepository, EntitySchema definitions, transactions with DataSource.transaction or QueryRunner, entity subscribers, migrations outside the Nest container, multiple named data sources, custom dataSourceFactory, connection retries, and mocking repositories with getRepositoryToken in tests. Use when the project uses or wants TypeORM (MySQL, PostgreSQL, SQLite, MariaDB, MSSQL), when adding an entity, repository, relation, transaction or migration, or when seeing "Nest can't resolve dependencies of XService (UserRepository)", missing entity metadata or data source naming problems. Not for Drizzle, Prisma, Mongoose, MikroORM or Sequelize (their own skills) or caching (nestjs-caching).
+compatibility: NestJS 12.x; @nestjs/typeorm, typeorm and a driver (pg, mysql2, better-sqlite3, …)
+metadata:
+  version: "0.1.0"
+  nestjs-major: "12"
+  docs-crawled: "2026-11-05"
+---
+
+# NestJS + TypeORM
+
+```bash
+npm i @nestjs/typeorm typeorm pg     # or mysql2, better-sqlite3, …
+```
+
+## Default setup
+
+```typescript
+// app.module.ts
+TypeOrmModule.forRootAsync({
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    type: 'postgres',
+    url: config.getOrThrow<string>('DATABASE_URL'),
+    autoLoadEntities: true,                          // entities registered via forFeature()
+    synchronize: false,                              // never true in production: can drop data
+    migrations: ['dist/migrations/*.js'],
+  }),
+}),
+
+// users/user.entity.ts
+@Entity()
+export class User {
+  @PrimaryGeneratedColumn('uuid') id: string;
+  @Column({ unique: true }) email: string;
+  @OneToMany(() => Photo, (photo) => photo.user) photos: Photo[];
+}
+
+// users/users.module.ts
+@Module({ imports: [TypeOrmModule.forFeature([User])], providers: [UsersService], exports: [UsersService] })
+export class UsersModule {}
+
+// users/users.service.ts
+@Injectable()
+export class UsersService {
+  constructor(@InjectRepository(User) private readonly users: Repository<User>) {}
+  findOne(id: string) { return this.users.findOneBy({ id }); }
+}
+```
+
+- Each feature module registers its own entities with `forFeature([...])`. To use a repository in another module, export `TypeOrmModule` from the owning module (or better, export a service).
+- `autoLoadEntities` skips entities only referenced through relations: register every entity with some `forFeature()`.
+- Extra module options: `retryAttempts` (10), `retryDelay` (3000 ms), `toRetry(err)`, `verboseRetryLog`, `manualInitialization`.
+- Inject `DataSource` / `EntityManager` directly when needed (from `typeorm`).
+
+## Transactions
+
+```typescript
+async transfer(from: string, to: string, amount: number) {
+  await this.dataSource.transaction(async (manager) => {
+    await manager.decrement(Account, { id: from }, 'balance', amount);
+    await manager.increment(Account, { id: to }, 'balance', amount);
+  });
+}
+```
+
+Use the `manager` passed to the callback for every statement in the transaction (repositories injected with `@InjectRepository` are outside it; use `manager.getRepository(Entity)`). For manual control use `dataSource.createQueryRunner()` → `connect()` → `startTransaction()` → `commitTransaction()` / `rollbackTransaction()` → `release()` in `finally`. For unit-testability, wrap QueryRunner creation in a small injectable factory instead of mocking `DataSource`.
+
+Packages that write in your transaction (`@nestjs/outbox`, `@nestjs/webhooks`) take the transaction's `EntityManager`, never `dataSource.manager`.
+
+## Migrations
+
+- Migrations run through TypeORM's CLI, outside the Nest container: no DI in migration classes.
+- Keep a standalone `DataSource` file (e.g. `src/data-source.ts` exporting `new DataSource({...})`) that reads the same env vars, for the CLI to generate and run migrations; set `migrationsRun` or run them in CI/deploy, never `synchronize` in production.
+- Review generated SQL before committing.
+
+## Other features
+
+- **Subscribers:** `@EventSubscriber()` class implementing `EntitySubscriberInterface<User>`, injecting `DataSource` and calling `dataSource.subscribers.push(this)`; add it to `providers`. Cannot be request-scoped.
+- **EntitySchema:** `new EntitySchema<User>({ name: 'User', target: User, columns, relations })` then `forFeature([UserSchema])`; `name` must equal the target class name.
+- **Multiple databases:** give each non-default data source a `name` (with `forRootAsync`, put `name` beside `useFactory`, not inside); `forFeature([Album], 'albumsConnection')`; `@InjectRepository(Album, 'albumsConnection')`, `@InjectDataSource('albumsConnection')`, `@InjectEntityManager('albumsConnection')`, `getDataSourceToken('albumsConnection')`. Unnamed data sources override each other.
+- **Custom factory:** `dataSourceFactory: async (options) => new DataSource(options!).initialize()` beside `useFactory`.
+
+## Testing
+
+```typescript
+const moduleRef = await Test.createTestingModule({
+  providers: [UsersService, { provide: getRepositoryToken(User), useValue: { findOneBy: vi.fn() } }],
+}).compile();
+```
+
+For integration/e2e tests, use a real database (Testcontainers, or SQLite only if queries are portable) with migrations applied, not `synchronize`.
+
+## Gotchas
+
+- "Nest can't resolve dependencies of UsersService (UserRepository at index [0])": `TypeOrmModule.forFeature([User])` is missing in that module.
+- "No metadata for User was found": entity not registered (`forFeature` or `entities`), or a glob pointing at `.ts` files in `dist`.
+- ESM projects: use `.js` extensions in relative imports and `() => Entity` lazy relation targets to avoid circular import crashes.
+- Load related data explicitly (`relations: { photos: true }`) rather than enabling eager relations everywhere.
+
+## Workflow
+
+- [ ] 1. Install driver; configure `forRootAsync` from validated config (nestjs-configuration).
+- [ ] 2. Create the entity, `forFeature` it in its module, inject the repository in a service.
+- [ ] 3. Generate and review a migration; apply it locally.
+- [ ] 4. Unit-test services with `getRepositoryToken` mocks; e2e against a real database.
+- [ ] 5. Build, lint, run tests, start the app.
+
+Sources: [TypeORM](https://docs.nestjs.com/data/typeorm) · [Database overview](https://docs.nestjs.com/data/overview)