MongoDB with NestJS: a practical MongoDB & NoSQL guide

Building production Node.js backends requires more than just connecting to a database—you need structure, consistency, and a way to share those schemas across your application. MongoDB with NestJS: a practical MongoDB & NoSQL guide walks you through the pattern that lets teams scale from prototype to production without rewriting your data layer. We'll cover how to set up schemas, inject models into services, and test everything reliably.

Why MongoDB and NestJS together

NestJS brings opinionated structure to Node.js, while MongoDB's flexible schema fits naturally into how JavaScript developers think about data. The combination isn't just popular—it's practical. When your team uses decorators for schema definition and dependency injection for model access, database code becomes predictable and testable. You avoid the friction of mapping between ORMs and your actual data shape, and you get compile-time hints about what fields exist on your documents.

In a recent e-commerce backend we built, this pattern let two developers confidently refactor product models without breaking queries in other services. The schema was the contract, and NestJS enforced it at the boundary.

@nestjs/mongoose module setup

Start by installing the core dependencies:

npm install @nestjs/mongoose mongoose

Then import MongooseModule into your root AppModule:

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';
import { ProductModule } from './product/product.module';

@Module({
  imports: [
    MongooseModule.forRoot('mongodb://localhost:27017/myapp'),
    ProductModule,
  ],
})
export class AppModule {}

For environments, use forRootAsync to pull the connection string from environment variables:

MongooseModule.forRootAsync({
  useFactory: (configService: ConfigService) => ({
    uri: configService.get('MONGO_URI'),
    retryAttempts: 3,
    retryDelay: 1000,
  }),
  inject: [ConfigService],
})

This approach lets you use different databases for different environments without changing code. We've used this pattern in production CRM systems where staging and production need isolated data.

Schema classes with decorators

NestJS schemas use TypeScript classes with property decorators. Each decorator tells Mongoose what the field is, its type, and validation rules. This keeps your schema definition readable and colocated with your types.

Here's a realistic product schema for an e-commerce platform:

import { Prop, Schema, SchemaFactory } from '@nestjs/mongoose';
import { Document } from 'mongoose';

@Schema({ timestamps: true })
export class Product extends Document {
  @Prop({ required: true, trim: true })
  name: string;

  @Prop({ required: true })
  sku: string;

  @Prop({ type: Number, required: true, min: 0 })
  price: number;

  @Prop({ type: Number, default: 0 })
  stock: number;

  @Prop({ type: [String], default: [] })
  tags: string[];

  @Prop({ required: true, enum: ['active', 'archived'] })
  status: string;

  @Prop({ type: Date, default: Date.now })
  lastReorderedAt: Date;
}

export const ProductSchema = SchemaFactory.createForClass(Product);

Notice the @Schema decorator with timestamps: true—this automatically adds createdAt and updatedAt fields. The @Prop decorators describe each field, including Mongoose options like required, default, min, and enum. This is cleaner than writing raw schema objects and gives you TypeScript completeness in your service code.

If you need nested objects, use a separate class and reference it:

@Schema()
export class Pricing {
  @Prop({ type: Number, required: true })
  cost: number;

  @Prop({ type: Number, required: true })
  margin: number;
}

@Schema({ timestamps: true })
export class Product extends Document {
  @Prop({ required: true })
  name: string;

  @Prop({ type: Pricing, required: true })
  pricing: Pricing;
}

This structure keeps your domain logic readable and your schema evolution manageable.

Inject models into services

Once your schema is defined, you register it in a feature module and inject it into services using NestJS dependency injection:

import { Module } from '@nestjs/common';
import { MongooseModule } from '@nestjs/mongoose';
import { Product, ProductSchema } from './schemas/product.schema';
import { ProductService } from './product.service';
import { ProductController } from './product.controller';

@Module({
  imports: [
    MongooseModule.forFeature([{ name: Product.name, schema: ProductSchema }]),
  ],
  providers: [ProductService],
  controllers: [ProductController],
})
export class ProductModule {}

Then in your service, inject the model with the @InjectModel decorator:

import { Injectable } from '@nestjs/common';
import { InjectModel } from '@nestjs/mongoose';
import { Model } from 'mongoose';
import { Product } from './schemas/product.schema';

@Injectable()
export class ProductService {
  constructor(
    @InjectModel(Product.name) private productModel: Model,
  ) {}

  async findBySkU(sku: string): Promise {
    return this.productModel.findOne({ sku }).lean().exec();
  }

  async updateStock(productId: string, delta: number): Promise {
    return this.productModel.findByIdAndUpdate(
      productId,
      { $inc: { stock: delta } },
      { new: true },
    ).exec();
  }

  async findActiveProducts(): Promise {
    return this.productModel
      .find({ status: 'active' })
      .sort({ createdAt: -1 })
      .lean()
      .exec();
  }
}

Key points here: use .lean() for read-heavy queries (you get plain JavaScript objects, not Mongoose documents, which is faster). Use findByIdAndUpdate with { new: true } to return the updated document. Always chain .exec() at the end so you get a proper Promise that integrates with NestJS lifecycle.

We've found this pattern particularly robust in trading systems where you're doing frequent atomic updates—the combination of @InjectModel and lean queries reduced memory overhead by about 20% compared to earlier versions where we weren't being deliberate about document type.

Test with in-memory or Testcontainers

Testing MongoDB code without a real database speeds up your test suite and avoids environment pollution. You have two main approaches: in-memory with mongodb-memory-server, or containerized with Testcontainers.

In-memory approach (fast, simpler setup):

import { Test, TestingModule } from '@nestjs/testing';
import { MongooseModule } from '@nestjs/mongoose';
import { MongoMemoryServer } from 'mongodb-memory-server';
import { ProductService } from './product.service';
import { Product, ProductSchema } from './schemas/product.schema';

let mongoServer: MongoMemoryServer;

beforeAll(async () => {
  mongoServer = await MongoMemoryServer.create();
  const moduleRef: TestingModule = await Test.createTestingModule({
    imports: [
      MongooseModule.forRoot(mongoServer.getUri()),
      MongooseModule.forFeature([
        { name: Product.name, schema: ProductSchema },
      ]),
    ],
    providers: [ProductService],
  }).compile();

  service = moduleRef.get(ProductService);
});

afterAll(async () => {
  await mongoServer.stop();
});

describe('ProductService', () => {
  it('should find product by SKU', async () => {
    const product = await service.create({
      name: 'Widget',
      sku: 'WID-001',
      price: 29.99,
      status: 'active',
    });

    const found = await service.findBySku('WID-001');
    expect(found.name).toBe('Widget');
  });
});

This runs in milliseconds and needs no external services. Perfect for unit and integration tests.

Testcontainers approach (more realistic, useful for complex queries):

import { MongoDBContainer } from 'testcontainers';

let container: MongoDBContainer;
let mongoUri: string;

beforeAll(async () => {
  container = await new MongoDBContainer().start();
  mongoUri = container.getConnectionString();

  const moduleRef = await Test.createTestingModule({
    imports: [
      MongooseModule.forRoot(mongoUri),
      MongooseModule.forFeature([
        { name: Product.name, schema: ProductSchema },
      ]),
    ],
    providers: [ProductService],
  }).compile();

  service = moduleRef.get(ProductService);
});

afterAll(async () => {
  await container.stop();
});

Testcontainers is slower (spinning up a real MongoDB) but catches more issues. Use it for complex aggregation pipelines or when you're testing sharded behavior. In our ride-hailing backend, we use Testcontainers for integration tests and in-memory for unit tests—best of both worlds.

Common mistakes

Forgetting to call .exec() on queries. Without it, you get a Query object, not a Promise. NestJS expects Promises, so your endpoints will hang. Always chain .exec().

Using Mongoose documents in lean queries. When you call .lean(), you get plain objects—no getters, no virtuals, no methods. If your code expects those, it will break silently. Use lean only for read queries where you just need data.

Not defining indexes in the schema. MongoDB won't automatically index common query fields. Your queries work, but they're slow. Define indexes upfront using the @Prop({ index: true }) decorator or compound indexes with @Schema({ indexes: [...] }).

Mixing connection strings and configurations. Hardcoding connection strings in code makes environment setup fragile. Always use ConfigService or environment variables, especially for production credentials.

Not using transactions in multi-document operations. If you're updating two documents and need consistency, use a transaction (available in MongoDB 4.0+). Without it, partial failures leave your data inconsistent.

Key takeaways

• Use MongooseModule.forRoot() in AppModule and MongooseModule.forFeature() in feature modules to keep database setup modular and testable.
• Define schemas as TypeScript classes with @Schema and @Prop decorators—this gives you type safety and keeps schema logic readable.
• Inject models with @InjectModel() and use .lean().exec() for performance on read-heavy queries.
• Test with mongodb-memory-server for speed (unit and integration tests) and Testcontainers for realism (complex queries, aggregations).
• Always use environment variables for connection strings, define indexes upfront, and add .exec() to every query chain.