Graceful Shutdown in Node.js: Preventing Data Loss and Dropped Connections During Deployments

When deploying updates or scaling down Kubernetes pods, backend applications are frequently terminated mid-flight. If your Node.js server shuts down abruptly without finishing active HTTP requests or flushing database connection pools, clients will experience dropped connections, corrupted transactions, and incomplete background tasks.

Implementing a robust Graceful Shutdown mechanism ensures zero dropped requests and pristine state management during service lifecycles.

1. The Anatomy of an Ungraceful Termination

When Kubernetes sends a SIGTERM signal to a container, the default behavior of a Node.js process is to terminate immediately.

• Active HTTP requests processing payloads are cut off instantly.
• Database transactions in flight are aborted with rollback errors.
• Redis subscriber connections remain dangling until TCP timeout.

To fix this, the application must intercept shutdown signals, stop accepting new connections, drain active traffic, and safely close all external resources.

2. Step-by-Step Implementation in Express / Node.js

Here is a production-ready template to manage graceful termination cleanly:

TypeScript

import http from "http";
import { app } from "./app"; // Express app instance
import { pool } from "./config/database";
import { redis } from "./config/redis";

const server = http.createServer(app);
const PORT = process.env.PORT || 3000;

server.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

// Track active connections to ensure complete draining
let isShuttingDown = false;

app.use((req, res, next) => {
  if (isShuttingDown) {
    res.setHeader("Connection", "close");
    return res.status(503).json({ error: "Service is shutting down" });
  }
  next();
});

// Handle termination signals securely
const handleShutdown = async (signal: string) => {
  console.log(`Received ${signal}. Starting graceful shutdown...`);
  isShuttingDown = true;

  // 1. Stop accepting new incoming connections
  server.close(async () => {
    console.log("HTTP server closed. No longer accepting new connections.");

    try {
      // 2. Close database connection pool (wait for active queries to complete)
      console.log("Closing database connection pool...");
      await pool.end();

      // 3. Disconnect Redis client safely
      console.log("Disconnecting Redis client...");
      await redis.quit();

      console.log("Graceful shutdown completed successfully.");
      process.exit(0);
    } catch (error) {
      console.error("Error during graceful shutdown cleanup:", error);
      process.exit(1);
    }
  });

  // Force shutdown timeout if draining takes too long (e.g., 10 seconds)
  setTimeout(() => {
    console.error("Forcing shutdown due to timeout expiration.");
    process.exit(1);
  }, 10000);
};

process.on("SIGTERM", () => handleShutdown("SIGTERM"));
process.on("SIGINT", () => handleShutdown("SIGINT"));

3. Kubernetes Probes Alignment

To ensure seamless zero-downtime rolling updates in Kubernetes, combine your graceful shutdown script with proper readiness and liveness configurations:

1. PreStop Hook: Add a short sleep delay (sleep 5) in your Pod manifest preStop hook to allow the Kubernetes load balancer (Ingress/Service) to deregister the pod IP before the application starts draining connections.
2. Readiness Probe: Ensure your health check endpoint returns HTTP 503 immediately once isShuttingDown is set to true.

Mastering graceful shutdown elevates your backend architecture from fragile scripts to resilient, enterprise-grade cloud services.