A deployment that simply restarts the application process almost always produces a few seconds of downtime, often invisible locally but very visible in production under load: requests failing with connection errors, WebSockets dropped, a user mid-form losing their session. "Zero-downtime" isn't a checkbox in a hosting provider's settings, it's a set of guarantees you build across several layers: routing, process lifecycle, and the database.

The concrete problem

Take a Node.js/NestJS API behind a reverse proxy, deployed via Docker. The naive deployment stops the container, pulls the new image, starts the new container. Between the old one stopping and the new one becoming available, every incoming request fails. Even with a fast startup (a few seconds), under enough traffic that still means hundreds of failed requests.

The basic mechanism: rolling deployment with health checks

The core idea behind zero-downtime is to never tear down the old version before the new one is proven healthy and ready to take traffic. Whether you're using Docker Compose with a simple orchestrator or Kubernetes, the principle is the same: start the new instance alongside the old one, wait for it to respond correctly to a health check, switch traffic over, and only then stop the old instance.

# Kubernetes example: rolling update with a readinessProbe
apiVersion: apps/v1
kind: Deployment
metadata:
  name: api-backend
spec:
  replicas: 3
  strategy:
    type: RollingUpdate
    rollingUpdate:
      maxUnavailable: 0
      maxSurge: 1
  template:
    spec:
      containers:
        - name: api
          image: registry.example.com/api:v2.4.0
          readinessProbe:
            httpGet:
              path: /health/ready
              port: 3000
            initialDelaySeconds: 5
            periodSeconds: 3
          livenessProbe:
            httpGet:
              path: /health/live
              port: 3000
            initialDelaySeconds: 10
            periodSeconds: 10

maxUnavailable: 0 guarantees that no healthy instance is removed before a new healthy instance replaces it. readinessProbe distinguishes "the process is running" (livenessProbe) from "the process is ready to serve user traffic" (readinessProbe) - a crucial distinction, since a Node.js process can start in a few milliseconds while still not having established its connection to PostgreSQL or loaded its cache.

// NestJS: a readiness endpoint that checks critical dependencies
@Controller("health")
export class HealthController {
  constructor(
    private readonly dataSource: DataSource,
    private readonly redis: Redis,
  ) {}

  @Get("ready")
  async ready() {
    await this.dataSource.query("SELECT 1");
    await this.redis.ping();
    return { status: "ok" };
  }

  @Get("live")
  live() {
    return { status: "ok" };
  }
}

The in-flight connections problem

Even with perfect routing, abruptly killing a process that still has in-flight HTTP requests, or open WebSocket connections, cuts those connections off. The fix is a graceful shutdown: on receiving SIGTERM, the process should stop accepting new connections, let in-flight requests finish, and only then exit.

// main.ts (NestJS)
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.enableShutdownHooks();

  process.on("SIGTERM", async () => {
    console.log("SIGTERM received, shutting down gracefully...");
    await app.close(); // lets in-flight requests finish
    process.exit(0);
  });

  await app.listen(3000);
}
bootstrap();

You also need a long enough grace period between SIGTERM and the forced SIGKILL (terminationGracePeriodSeconds in Kubernetes, often 30 seconds by default) so that long-running requests (a file upload, a report generation job) have time to finish instead of being killed mid-flight.

The real trap: database migrations

This is where most "zero-downtime" deployments actually fail in practice. During a rolling deployment, the old and the new version of the code run simultaneously for anywhere from a few seconds to several minutes, and both query the same database. A migration that renames a column or drops a column still referenced by the old code breaks the old version while it's still handling live traffic.

-- BAD: breaks the old code version mid-rollout
ALTER TABLE orders RENAME COLUMN client_id TO customer_id;

The right approach is a multi-step, backward-compatible migration spread across several distinct releases:

-- Step 1 (release N): add the new column, don't touch the old one
ALTER TABLE orders ADD COLUMN customer_id INT;

-- Release N's code writes to BOTH columns (client_id and customer_id)
-- and still reads from client_id.

-- Step 2 (release N+1, once N is fully rolled out):
-- backfill existing rows
UPDATE orders SET customer_id = client_id WHERE customer_id IS NULL;

-- Release N+1's code now reads from customer_id.

-- Step 3 (release N+2, once N+1 is stable):
-- drop the now-unused old column
ALTER TABLE orders DROP COLUMN client_id;

This "expand / migrate / contract" pattern applies to any schema change that alters a contract already consumed by code running in production: column renames, type changes, table drops. It requires discipline (several releases for a single schema change), but that's the actual price of real zero-downtime.

Rolling, blue-green, canary: three strategies, three tradeoffs

The rolling deployment described above is only one possible strategy, and the right choice depends on the acceptable risk level and the infrastructure capacity available.

Blue-green deployment keeps two complete, identical production environments (blue and green). The new version is deployed entirely onto the inactive environment, tested under real conditions with no user traffic, and then the router instantly switches all traffic from one environment to the other. The advantage is immediate rollback: if a problem shows up, you switch the router back to the previous environment in seconds, without redeploying anything. The cost is maintaining double the infrastructure capacity, at least during the transition window.

# Simplified example with a tag-driven load balancer
# 1. Deploy the new version onto the "green" environment
kubectl apply -f deployment-green.yaml
kubectl rollout status deployment/api-green

# 2. Switch the service to green once checks pass
kubectl patch service api-service -p '{"spec":{"selector":{"env":"green"}}}'

# 3. If something's wrong, instant rollback to blue
kubectl patch service api-service -p '{"spec":{"selector":{"env":"blue"}}}'

Canary deployment routes a small fraction of real traffic (5%, then 25%, then gradually 100%) to the new version, while watching error and latency metrics at each step. It's the most cautious strategy for catching a bug that only shows up under real traffic (an edge case in production data that tests never covered), at the cost of more complex implementation: it needs weighted routing at the load balancer or service mesh level, plus a clear definition of which metrics trigger an automatic rollback.

Rolling deployment remains the most common default because it needs neither doubled infrastructure nor sophisticated weighted routing, but it offers weaker instant-rollback guarantees than blue-green: rolling back means redeploying the old version, not just flipping a pointer.

Draining database connections

A frequent blind spot in application-level graceful shutdown is the database connection pool. Closing the HTTP server isn't enough if the PostgreSQL connection pool stays open and the orchestrator kills the process before active connections are properly released: that can leave half-committed transactions or unreleased locks hanging until the database server's own connection timeout kicks in.

process.on("SIGTERM", async () => {
  await app.close();        // stop accepting new HTTP requests
  await dataSource.destroy(); // cleanly close the PostgreSQL connection pool
  process.exit(0);
});

Order matters: close the HTTP layer first so no new request tries to grab a connection, let in-flight requests finish naturally (which is what app.close() does in NestJS while waiting for active handlers), and only then close the database pool. Reversing that order risks failing in-flight requests with a lost-connection error, a symptom that looks like an application bug but is actually a shutdown sequencing problem.

Diagnosing a deployment that still causes an outage

Typical symptoms to look for in logs and monitoring at the exact moment of a deployment:

  • A spike in 502/503 errors at the reverse proxy: missing or misconfigured health check, or a nonzero maxUnavailable.
  • Application errors like column does not exist right after a deploy: a non-backward-compatible migration, with the old version still serving traffic.
  • WebSocket connections dropping in bulk at a fixed time: missing graceful shutdown, or SIGKILL firing too quickly after SIGTERM.

When this isn't enough

For heavy migrations on very large tables (tens of millions of rows), even a backward-compatible ALTER TABLE ADD COLUMN can lock the table long enough to affect latency, depending on the database engine and version. PostgreSQL has handled ADD COLUMN with a default value well since version 11, without a full table rewrite, but a bulk backfill UPDATE should be done in small batches with pauses between them, not as a single transaction, to avoid exhausting connections or blocking concurrent writes.

Takeaway

Real zero-downtime rests on three independent guarantees that all have to hold at the same time: routing never shifts traffic to an instance that hasn't proven itself healthy, the outgoing process finishes its current work before dying, and the database schema stays compatible with two versions of the code running side by side during the transition. Missing the third one is the most common cause of incidents even when the deployment infrastructure itself is otherwise solid.