Delivery Basics

8 examples to align Node.js deploy frequency with database migration risk - 6 basic and 2 intermediate.

Prerequisites

• CI/CD with distinct PR checks and release promotion (see CI/CD Basics)
• Migrations in version control (Prisma, Flyway, or node-pg-migrate)
• Staging environment that mirrors production pool sizes
• DORA baseline captured (see DORA Metrics for Node Teams)

Basic Examples

1. Node Deploys Fast; Databases Do Not

• Stateless Node containers are cheap to redeploy
• Schema changes are the brake - plan migrations before promising daily prod pushes
• Feature flags decouple code deploy from behavior exposure

Related: DORA Metrics for Node Teams - measure delivery health

2. Expand-Contract Migration Pattern

Expand: Add nullable column or new table - deploy API that writes both old and new.

Contract: Backfill data; switch reads to new shape.

Delete: Remove old column in later release after rollback window closes.

-- Expand (deploy 1)
ALTER TABLE orders ADD COLUMN status_v2 TEXT;
 
-- Contract (deploy 2) - app writes status_v2, reads with COALESCE
-- Delete (deploy 3)
ALTER TABLE orders DROP COLUMN status;

• Each expand step must be backward-compatible with previous API image
• Never drop a column the previous release still reads

3. PR Pipeline vs Release Pipeline

PR pipeline (every push):
  lint → typecheck → unit tests → integration (Testcontainers)
 
Release pipeline (merge to main):
  build image → scan → deploy staging → smoke → manual/auto promote prod

• PR pipeline proves code; release pipeline proves artifact
• Tag images with gitSha, not latest
• Block release if migration has not run in staging

4. API and Worker Deploy Order

Schema expand migration (staging + prod)
  → deploy API (writes new fields, reads fallback)
  → deploy workers (process new job shape)
  → backfill job (if needed)
  → deploy API (reads new fields only)
  → contract migration

• Workers lagging API is safer than workers ahead of API on destructive changes
• Pause workers during incompatible intermediate states
• Document order in docs/deploy-order.md per service

5. Migration Risk Checklist

[ ] Backward-compatible with N-1 API image?
[ ] Backward-compatible with N-1 worker image?
[ ] Index created CONCURRENTLY (Postgres)?
[ ] Lock time estimated for ALTER?
[ ] Rollback path documented (forward-fix vs undo)?
[ ] Staging load test after migration?

• ALTER TABLE on large tables needs maintenance window or online schema tool
• Prisma migrate deploy in CI before k8s rollout

6. Environment Promotion Flow

feature branch → PR → main → staging (auto) → production (gated)

• Staging uses production-like data volume subset, not empty DB
• Smoke tests hit /health/ready and one critical write/read path
• Production promotion requires change ticket for regulated industries

Intermediate Examples

7. Coupling Delivery to Error Budget

Error budget remaining > 50%  → normal deploy cadence
Error budget 20-50%           → deploys require TL approval
Error budget < 20%            → freeze feature deploys; fixes only

• SLO burn ties delivery speed to reliability (see SLOs and Error Budgets)
• Node teams often deploy too fast for DB migration capacity - budget protects both

8. Release Notes for Backend

## orders-api v2.14.0 (2026-07-09)
- Migration: 20260709_add_status_v2 (expand, backward-compatible)
- Deploy order: migrate → API → workers
- Feature flag: new-checkout (default off)
- Rollback: rollout undo to v2.13.2; migration is forward-only

• Support and PM read this; link from Slack #releases
• Explicit rollback constraints prevent 3 a.m. surprises

FAQs

Related

• Feature Flags - decouple deploy from exposure
• Canary & Progressive Delivery - safe promotion
• DORA Metrics for Node Teams - delivery metrics
• CI/CD Basics - pipeline separation
• Enterprise Delivery Best Practices - condensed checklist

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.