Graceful Shutdown in Node.js

Open resources leak. A database transaction that never commits or rolls back holds its locks until the connection times out on the server side. A queue consumer that vanishes mid-message can trigger a redelivery or drop the message entirely.

The orchestrator escalates. Ignore SIGTERM, and Kubernetes waits out its grace period, then sends SIGKILL. Now you've turned a clean shutdown into a hard kill — exactly what you were trying to avoid.

This is the flip side of the deployment discipline I wrote about in the five pillars of modern software delivery: fast, frequent releases only stay safe when each instance can leave the pool without dropping traffic.

The shutdown sequence

A correct shutdown always follows the same order: receive the signal, stop accepting connections, drain what's running, close downstream resources, exit.

The timeout branch matters as much as the happy path. A slow request might never finish, and you can't wait forever, so a watchdog forces the exit once a deadline passes.

Handling the signal

Start with a plain HTTP server so the mechanics are clear. server.close() stops accepting new connections and fires its callback once all the existing ones have ended.

Now add the shutdown handler. It runs the same logic for both SIGTERM (orchestrators) and SIGINT (Ctrl+C in local dev), guards against running twice, and arms a force-exit timer.

Three details do the real work. The shuttingDown flag stops a second signal from restarting the sequence. The forceExit timer is the watchdog that guarantees the process leaves even when a connection hangs, and unref() lets that timer sit in the background without keeping the event loop alive by itself. The onClose callback is where you release everything the server depended on.

Closing your resources

Draining connections is only half the job. The database pool, Redis client, and any queue consumers need to close too — and they should close after the server stops accepting requests, so nothing tries to use a connection you just tore down.

If you run several resources, close them together and don't let one failure strand the rest.

On Fastify

On Fastify, most of this is built in. Calling app.close() stops accepting connections, waits for in-flight requests, and runs every onClose hook in reverse registration order — so a database plugin registered with fastify-plugin gets torn down for you. You still own the signal handlers and the force-exit timer.

This fits how Fastify already manages a shared connection pool, which I covered in connecting Fastify to PostgreSQL — the pool you decorate onto the instance is exactly what onClose should drain.

One more thing for Kubernetes

Here's a subtlety that catches people in production. When a pod is terminating, Kubernetes sends SIGTERM and removes the pod from the Service endpoints at the same time — but that removal spreads asynchronously. For a brief window, the load balancer may still send new requests to a pod that already called server.close(), and those get refused.

The fix is to delay the close by a couple of seconds after SIGTERM, giving the endpoint removal time to propagate before you stop accepting connections. A preStop hook with a short sleep, or a small delay in your handler, closes the gap.

Wire the signal handler in once, give it a sensible timeout, and your deploys stop leaking requests. It's a one-time cost that pays off on every release after.