MongoDB with Mongoose in NestJS

This chapter follows Application lifecycle hooks in NestJS.

Mongoose already gives MongoDB schemas, validation, and models. What it does not give is a place in a Nest application: who opens the connection, how a service gets a model, and how a test replaces it. @nestjs/mongoose answers those with the patterns from the previous chapters. The connection is a forRootAsync() dynamic module, each feature registers its models with forFeature(), and models are injected by token. For Mongoose itself, schemas, queries, and population, see Mongoose with MongoDB.

Connecting

1
pnpm add @nestjs/mongoose mongoose

The connection is opened once, in the root module, with the URI from configuration:

1
import { Module } from '@nestjs/common';
2
import { ConfigModule, ConfigService } from '@nestjs/config';
3
import { MongooseModule } from '@nestjs/mongoose';
4
import { CatsModule } from './cats/cats.module';
5

6
@Module({
7
  imports: [
8
    ConfigModule.forRoot({ isGlobal: true }),
9
    MongooseModule.forRootAsync({
10
      inject: [ConfigService],
11
      useFactory: (config: ConfigService) => ({
12
        uri: config.getOrThrow<string>('MONGODB_URI'),
13
      }),
14
    }),
15
    CatsModule,
16
  ],
17
})
18
export class AppModule {}

Nest waits for the connection before it finishes starting, so a wrong URI fails at startup. The module also closes the connection during shutdown, which is one more reason to call app.enableShutdownHooks().

Defining a schema

Schemas can be written as classes with decorators. SchemaFactory turns the class into a regular Mongoose schema:

1
import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
2
import { HydratedDocument, Types } from 'mongoose';
3

4
@Schema({ timestamps: true })
5
export class Cat {
6
  @Prop({ required: true, trim: true })
7
  name: string;
8

9
  @Prop({ min: 0 })
10
  age: number;
11

12
  @Prop({ index: true })
13
  breed: string;
14

15
  @Prop({ type: Types.ObjectId, ref: 'User', required: true })
16
  owner: Types.ObjectId;
17
}
18

19
export type CatDocument = HydratedDocument<Cat>;
20
export const CatSchema = SchemaFactory.createForClass(Cat);
21
CatSchema.index({ owner: 1, name: 1 }, { unique: true });

The class is the type of a stored document. It is a separate thing from the CreateCatDto that validates a request: the DTO decides what a client may send, the schema decides what the database stores, and the two tend to differ (owner comes from the authenticated user, not from the body).

Registering and injecting a model

A feature module registers the models it uses on the shared connection:

1
import { Module } from '@nestjs/common';
2
import { MongooseModule } from '@nestjs/mongoose';
3
import { CatsController } from './cats.controller';
4
import { CatsService } from './cats.service';
5
import { Cat, CatSchema } from './schemas/cat.schema';
6

7
@Module({
8
  imports: [MongooseModule.forFeature([{ name: Cat.name, schema: CatSchema }])],
9
  controllers: [CatsController],
10
  providers: [CatsService],
11
})
12
export class CatsModule {}

The service injects the model with @InjectModel() and uses the normal Mongoose API:

1
import { Injectable, NotFoundException } from '@nestjs/common';
2
import { InjectModel } from '@nestjs/mongoose';
3
import { isValidObjectId, Model } from 'mongoose';
4
import { CreateCatDto } from './dto/create-cat.dto';
5
import { Cat } from './schemas/cat.schema';
6

7
@Injectable()
8
export class CatsService {
9
  constructor(@InjectModel(Cat.name) private readonly catModel: Model<Cat>) {}
10

11
  create(dto: CreateCatDto, ownerId: string) {
12
    return this.catModel.create({ ...dto, owner: ownerId });
13
  }
14

15
  findAll(breed?: string) {
16
    return this.catModel.find(breed ? { breed } : {}).lean().exec();
17
  }
18

19
  async findOne(id: string) {
20
    const cat = isValidObjectId(id) ? await this.catModel.findById(id).lean().exec() : null;
21
    if (!cat) throw new NotFoundException(`Cat ${id} not found`);
22
    return cat;
23
  }
24
}

lean() returns plain objects instead of full Mongoose documents. That is faster for reads that go straight into a response. Leave it off when the code needs document methods such as save().

Mapping database errors

A duplicate key violates the unique index and arrives as a Mongo error with code 11000. Left alone, the built-in filter answers 500. A small exception filter turns it into a 409:

1
import { ArgumentsHost, Catch, ConflictException, ExceptionFilter } from '@nestjs/common';
2
import { BaseExceptionFilter } from '@nestjs/core';
3
import { mongo } from 'mongoose';
4

5
@Catch(mongo.MongoServerError)
6
export class MongoDuplicateKeyFilter extends BaseExceptionFilter implements ExceptionFilter {
7
  catch(exception: mongo.MongoServerError, host: ArgumentsHost) {
8
    if (exception.code === 11000) {
9
      return super.catch(new ConflictException('Resource already exists', { cause: exception }), host);
10
    }
11
    return super.catch(exception, host);
12
  }
13
}

Extending BaseExceptionFilter hands the response back to Nest’s built-in filter, so the 409 has the same JSON shape as every other HTTP exception. When registered with APP_FILTER, BaseExceptionFilter receives the HTTP adapter through the injector, so the class needs no constructor of its own.

Testing with a model

@InjectModel(Cat.name) resolves to a provider whose token is getModelToken(Cat.name). A unit test supplies a fake under that token and never touches a database:

1
import { getModelToken } from '@nestjs/mongoose';
2
import { Test } from '@nestjs/testing';
3
import { CatsService } from './cats.service';
4
import { Cat } from './schemas/cat.schema';
5

6
describe('CatsService', () => {
7
  const catModel = { find: jest.fn(), findById: jest.fn(), create: jest.fn() };
8
  let service: CatsService;
9

10
  beforeEach(async () => {
11
    const moduleRef = await Test.createTestingModule({
12
      providers: [CatsService, { provide: getModelToken(Cat.name), useValue: catModel }],
13
    }).compile();
14
    service = moduleRef.get(CatsService);
15
  });
16
});

For tests that should exercise real queries and indexes, mongodb-memory-server starts a throwaway MongoDB that forRootAsync() can point at. Testing NestJS applications covers both kinds of test.

Next: Authentication in NestJS.