Lifecycle hooks and graceful shutdown

The lifecycle has two phases, each with a fixed order

A Nest application has a birth and a death, and both are ordered events you can hook into. Knowing the order is the whole game: it tells you when your injected dependencies are guaranteed ready, and when it is safe to close them.

Init runs bottom-up. When you call app.listen() (or app.init()), Nest resolves the dependency graph and then fires, per provider/module:

1. onModuleInit() — called for a module after that module’s own dependencies are resolved. This is the first moment your injected providers are guaranteed constructed and wired.
2. onApplicationBootstrap() — called after every module has finished initializing, just before the server starts listening. This is the first moment the whole app is ready, including providers from other modules.

Teardown runs in reverse. On app.close() or a termination signal, Nest unwinds in reverse dependency order:

1. onModuleDestroy() — the termination signal has arrived; begin tearing down.
2. beforeApplicationShutdown(signal) — runs after all onModuleDestroy() handlers, before connections are closed; receives the signal ("SIGTERM", "SIGINT", …).
3. onApplicationShutdown(signal) — runs after connections are closed; the last breath, where you release pools, queue consumers, and clients.

Reverse order matters: a module that depends on the database is torn down before the database module, so it never tries to use a connection that’s already gone. Each interface contributes one method — OnModuleInit, OnApplicationBootstrap, OnModuleDestroy, BeforeApplicationShutdown, OnApplicationShutdown — and you implement only the ones you need. Async hooks are awaited: returning a Promise pauses the sequence until it resolves.

onModuleInit vs the constructor

A provider’s constructor runs at instantiation, while Nest is still wiring the graph. At that point your injected dependencies exist (they were constructed first), but any async setup they need — a TCP connection, a primed cache, a fetched config — has not run. Doing real I/O in the constructor is a trap: constructors can’t be async, so you either block synchronously or fire-and-forget a floating promise, and you have no clean place to handle failure.

onModuleInit() is the answer. When you need to open a connection, prime a cache, or verify that an external service is reachable before traffic arrives, this is where that code belongs. It runs once, right after the module’s dependencies resolve, it can be async, and Nest awaits it before moving on. That makes it the correct home for warm-up that needs ready dependencies:

import { Injectable, OnModuleInit, OnApplicationShutdown } from '@nestjs/common';
import { Pool } from 'pg';

@Injectable()
export class DatabaseService implements OnModuleInit, OnApplicationShutdown {
  private pool!: Pool;

  constructor(private readonly config: ConfigService) {
    // constructor: deps exist, but do NO async I/O here
    this.pool = new Pool({ connectionString: this.config.get('DB_URL') });
  }

  async onModuleInit(): Promise<void> {
    // warm-up: dependencies are ready, await is honored
    await this.pool.query('SELECT 1'); // prove the pool connects before we serve traffic
  }

  async onApplicationShutdown(signal: string): Promise<void> {
    // drain: connections close last, after in-flight work is done
    console.log(`shutting down on ${signal}`);
    await this.pool.end(); // close every client in the pool
  }
}

The split is deliberate: construct cheaply, connect in onModuleInit, and release in onApplicationShutdown. If the warm-up query throws, Nest aborts startup with a clear error instead of booting a service that can’t reach its database. Use onApplicationBootstrap instead of onModuleInit only when the warm-up depends on another module being fully up — e.g. priming a cache from a service defined in a different module that must finish its own onModuleInit first.

Graceful shutdown, done right

Shutdown hooks do nothing unless you opt in. app.enableShutdownHooks() registers process listeners for SIGTERM/SIGINT so Nest can fire the teardown sequence; it is off by default because attaching signal listeners has a cost and Nest won’t impose it silently.

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule, {
    // also force-close idle Keep-Alive sockets so the process can actually exit
    forceCloseConnections: true,
  });
  app.enableShutdownHooks(); // REQUIRED: otherwise SIGTERM just kills the process
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

Now the actual sequence on SIGTERM: stop accepting new work, drain in-flight requests, then close resources. Nest’s HTTP adapter stops the server and waits for open responses to finish before resolving the close — but long-lived Connection: Keep-Alive sockets can keep the process hostage, which is why forceCloseConnections exists. Once requests are drained, your onApplicationShutdown closes the DB pool, queue consumers, and Kafka clients — in reverse dependency order, so nothing closes a resource another provider still needs.