What is a blue-green deployment for a monolith and how does it work?
A blue-green deployment for a monolith runs two complete, identical production environments side by side. Both are built from the same artifact and the same configuration, differing only in the version they run. One environment (say, blue) serves all live traffic. The other (green) sits idle until you deploy the new release to it. Both point at the same database. A single switch point, usually a load balancer or reverse proxy, decides which environment receives requests.
A release works like this: deploy the new version to the idle environment, verify it against production infrastructure, then flip the switch. If something breaks, flip it back. The old environment is still running and warm, so a code rollback takes seconds rather than a full redeploy.
Teams adopt it for three reasons:
- Fast cutover. Users move to the new version in one step, not through a slow rolling update.
- Fast code rollback. The previous version stays deployed and ready.
- Testing the exact release. You exercise the real artifact, with production config and connectivity, before any customer touches it.
The pattern fits teams releasing a stateful monolith that cannot accept maintenance windows.
Routing is the easy part of this guide. The hard part is that for some period, two versions of your application run against the same database, the same session store and the same job queues. Every schema change, serialized object and queued message has to work for both versions at once. Most of what follows deals with that constraint.
+-------------------+
| Users |
+---------+---------+
|
v
+-----------------------------+
| Load balancer / proxy |
| (single switch point) |
+------+---------------+------+
| :
live | : idle: no traffic
v v
+----------------------+ +----------------------+
| BLUE environment | | GREEN environment |
| release v1 (live) | | release v2 (idle) |
| same build pipeline | | same build pipeline |
| same config | | same config |
+----------+-----------+ +-----------+----------+
| |
+-------------+-------------+
|
v
+--------------------------------------------------+
| SHARED STATE: read and written by v1 and v2 |
| +------------+ +---------------+ +-----------+|
| | Database | | Session store | | Job queue ||
| +------------+ +---------------+ +-----------+|
+--------------------------------------------------+
Easy part: flip the switch. Hard part: shared state must suit both.
Blue and green are identical environments behind one switch point, and both use the same database, session store and job queue, so every change to that shared state must work for both versions at once.
Which traffic switch should you use: load balancer, reverse proxy or DNS?
The switch itself is the one piece that should be boring: it needs to flip quickly, flip back just as quickly, and behave the same way for every client.
| Mechanism | Cutover speed | Reversal speed | Predictability |
|---|---|---|---|
| Load balancer target swap | Seconds | Seconds | High; one control point |
| Reverse proxy upstream swap | Seconds (config reload) | Seconds | High; atomic per reload |
| DNS record change | Minutes to hours | Same as cutover | Low; depends on caches you don't control |
DNS is the weakest lever because the change doesn't happen in one place. Resolvers honour the TTL, but some ignore it, and many clients cache lookups longer than the TTL allows: JVMs, mobile apps, long-lived HTTP clients and connection pools. During a rollback, some users stay on the broken version until their caches expire, and you can't force that.
With a reverse proxy, define blue and green upstream blocks, point proxy_pass at one of them, and reload. In nginx, nginx -s reload starts new workers with the new config. Old workers stop accepting connections and finish requests they are already serving. Rolling back is the same one-line edit in the other direction.
That drain matters on the old side too. Shut blue down gracefully: stop accepting new requests, let current ones finish, then exit. Set a drain window that is longer than your slowest normal request. Long-running requests and websockets that outlive the window will be cut off. Clients therefore need reconnect logic, and long operations must be idempotent so they can be retried safely.
# Main context: cap how long old workers may drain after a reload.
# Set it longer than your slowest normal request; websockets and
# long requests still open after this are closed by nginx.
worker_shutdown_timeout 60s;
events {}
http {
upstream blue {
server 10.0.1.10:8080; # current release
}
upstream green {
server 10.0.2.10:8080; # new release
}
server {
listen 80;
location / {
# The switch: change this one word (green <-> blue), then run
# nginx -t && nginx -s reload
# New workers take new connections; old workers finish in-flight ones.
proxy_pass
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# Allow websocket upgrades; these connections stay pinned to the
# old worker and old backend until they close or the drain timeout hits.
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 300s;
}
}
}
A minimal nginx config where cutover and rollback are a one-word proxy_pass edit plus a validated reload, with worker_shutdown_timeout bounding how long old workers drain in-flight requests and websockets.
How do you keep the database compatible with both versions?
Blue and green run against the same database, so during the switch, and for as long as rollback stays possible, the schema must work with both releases. Any migration that breaks the old code, such as renaming or dropping a column or adding a NOT NULL column without a default, turns a traffic flip into an outage. Rolling back would then mean reversing the migration under load.
The fix is expand/contract, also called parallel change. Additive migrations ship first. Destructive ones wait until no running code depends on the old shape. A column rename from full_name to display_name takes several deploys:
- Expand:
ALTER TABLE users ADD COLUMN display_name text NULL. The old code ignores the new column. - Dual-write: on every save, the app writes both
full_nameanddisplay_name. It still readsfull_name. - Backfill:
UPDATE users SET display_name = full_name WHERE display_name IS NULL, run in small batches by primary key range. Batching avoids long locks and replication lag. - Switch reads: the app reads
display_nameand keeps dual-writing. - Stop old writes: the app writes only
display_name. - Contract: drop
full_name.
| Step | Safe to roll back the app? | Notes |
|---|---|---|
| Expand | Yes | Nullable column is invisible to old code |
| Dual-write | Yes | Old column stays current |
| Backfill | Yes | Data-only, re-runnable |
| Switch reads | Yes | Previous release reads the old column, still written |
| Stop old writes | Only with re-backfill | Old column goes stale |
| Contract | No | Data is gone; restore from backup |
Each step can be deployed and observed on its own. The cost is that one logical change now spans several releases. Track the leftover dual-write code and dead columns as explicit tickets, or they will stay in the codebase indefinitely.
# Steps 2 and 3 of the full_name -> display_name rename.
# Assumes a PostgreSQL DB-API connection (e.g. psycopg2) with %s placeholders.
import time
BATCH_SIZE = 5000 # rows per transaction; keep locks short
PAUSE_SECONDS = 0.1 # give replicas time to catch up between batches
def save_user_name(conn, user_id, name):
# Dual-write: keep the old column current so the previous release
# (which still reads full_name) sees correct data after a rollback.
with conn.cursor() as cur:
cur.execute(
"UPDATE users SET full_name = %s, display_name = %s WHERE id = %s",
(name, name, user_id),
)
conn.commit()
def backfill_display_name(conn):
# Backfill in primary-key ranges. Re-runnable: rows already filled
# (by dual-write or an earlier run) are skipped by the IS NULL filter.
with conn.cursor() as cur:
cur.execute("SELECT COALESCE(MAX(id), 0) FROM users")
max_id = cur.fetchone()[0]
start = 0
while start <= max_id:
end = start + BATCH_SIZE
with conn.cursor() as cur:
cur.execute(
"UPDATE users SET display_name = full_name "
"WHERE id >= %s AND id < %s AND display_name IS NULL",
(start, end),
)
conn.commit() # one short transaction per batch
start = end
time.sleep(PAUSE_SECONDS)
The dual-write save path and a re-runnable backfill that copies full_name into display_name in short, primary-key-ranged transactions.
How do you handle sessions, caches and background jobs during the switch?
The database is not the only state that must survive the switch. Anything held in process memory disappears when traffic moves, and anything written by one version may be read by the other.
Sessions and caches
If sessions live in the application's memory, every user on blue is logged out the moment traffic moves to green. Move them into a shared store that both environments reach, or use signed tokens that carry the session data so any instance can validate them. Both versions must then read each other's formats. Green will receive sessions that blue created, and after a rollback blue will receive sessions that green created. Put a version in cache and session keys, so incompatible shapes never collide, or deserialize tolerantly: ignore unknown fields and default the missing ones. The same rule applies to cached objects. A cache entry written by green with a new field must not crash blue.
Background jobs and schedulers
HTTP traffic is easy to move. Workers are not. If both environments run the scheduler, nightly jobs fire twice and invoices go out twice. Exactly one environment should own schedulers and cron-style work at any time. A simple way to enforce this is to gate the scheduler on an ownership flag in shared storage. For example, each environment checks whether scheduler_owner equals its own color before enqueuing anything. You can also use a lease-based leader lock with an expiry, so a crashed owner releases control.
The switch then has two steps: move HTTP traffic, then move scheduler and worker ownership. Queue payloads also cross versions, so version them and keep both consumers able to process jobs already waiting in the queue.
import os, socket, time
import redis
COLOR = os.environ["DEPLOY_COLOR"] # "blue" or "green", set per environment
INSTANCE = f"{COLOR}:{socket.gethostname()}"
LEASE_MS = 30_000
r = redis.Redis(host="redis.internal", port=6379, decode_responses=True)
# Extend the lease only if this instance still holds it (atomic check-and-extend).
RENEW = """
if redis.call('get', KEYS[1]) == ARGV[1] then
return redis.call('pexpire', KEYS[1], ARGV[2])
end
return 0
"""
def owns_scheduler() -> bool:
# Environment-level gate: the deploy flips this key as the second switch step.
if r.get("scheduler_owner") != COLOR:
return False
# Instance-level gate: one instance in the owning color holds an expiring lease,
# so a crashed owner releases control after LEASE_MS.
if r.set("scheduler_lease", INSTANCE, nx=True, px=LEASE_MS):
return True
return r.eval(RENEW, 1, "scheduler_lease", INSTANCE, LEASE_MS) == 1
def run_due_jobs() -> None:
# Version the payload so both blue and green consumers can process it.
job = {"v": 2, "type": "nightly_invoices", "date": time.strftime("%Y-%m-%d")}
... # enqueue job here
while True:
# Re-check every tick: if the switch moves ownership, this side stops enqueuing.
if owns_scheduler():
run_due_jobs()
time.sleep(10)
A scheduler loop that enqueues work only when its environment's color matches a shared scheduler_owner flag and it holds an expiring Redis lease, so exactly one environment and one instance runs cron-style jobs during and after the switch.
Implementing the release: verification, warm-up and rollback runbook
Build, verify, warm
Build the idle side from the exact artifact and config bundle you will promote. Do not rebuild it, and do not hand-edit settings. Environment drift is the most common reason a green that looked healthy fails under real traffic.
Test green through an internal route that real users cannot reach. A liveness endpoint only proves the process started. The health check script that accompanies this section goes further: it reads and writes a test row, checks that the schema version matches what the build expects, and calls each external dependency.
Smoke tests run against real integrations, so guard their side effects:
- Point payment providers at sandbox credentials, or use a test-account flag.
- Route outbound email and webhooks to a sink.
- Throttle probes so you do not use up third-party rate limits that blue still needs.
Next, warm green with replayed or synthetic read traffic:
- Fill the caches.
- Open the connection pools.
- Let the JIT compile the hot paths.
If you skip this, the first real requests hit cold paths. Latency spikes, upstream timeouts fire, and retries amplify the load into a cascade.
Rollback runbook
A fast rollback means pointing the traffic switch back at blue. It reverts code and config in seconds. It cannot undo:
- rows written in formats only green understands
- migrations that have already run
- emails, charges or webhooks already sent
Roll forward instead if any of these is true:
- Blue cannot read the data green has written.
- A migration has dropped or rewritten columns.
- The defect is small and can be fixed faster than the data can be reconciled.
Decide on these criteria before the release, not during the incident.
What does blue-green cost, and where does it save engineering time?
The main recurring cost is the app tier. During each release you run two production-capacity copies of the monolith. The database, message broker and shared cache are not duplicated, because both sides use them. That leaves one decision: how large the idle side stays between releases.
| Idle side between releases | Extra app-tier compute | Before a release | Instant rollback available |
|---|---|---|---|
| Kept at full size | About 2× continuously | Nothing to provision | At any time |
| Scaled down | Only during release windows | Scale up and warm before the switch | Until you scale it down again |
Illustrative estimate (assumed numbers, not a benchmark)
Assumed inputs: N = 6 instances per side, C = $0.20 per instance-hour, H = 730 hours per month, R = 8 releases per month, and W = 3 hours with both sides at full size per release.
- Full-size idle: extra = N × C × H = 6 × 0.20 × 730 = $876/month
- Scaled-down idle: extra = N × C × R × W = 6 × 0.20 × 8 × 3 = $28.80/month
Scaling down is far cheaper. The trade-off is that the rollback target eventually disappears, and each release takes longer to start.
The development cost is less visible. Expand/contract turns every destructive schema change into at least two releases. Code has to tolerate both the old and new shapes of the data in between. Someone also has to schedule the contract step. Without that follow-up, unused columns and compatibility branches pile up.
The time savings are large. Deploys happen during working hours with the whole team available, instead of in off-hours maintenance windows. When an incident is caused by code, rollback is a traffic switch rather than a rebuild and redeploy. Green is also verified against real production configuration and data before it takes traffic, so it catches environment problems that staging usually misses.
When should you avoid blue-green, and what are the alternatives?
Those benefits come at a price that not every team should pay. If you run a single app with a small team and your users tolerate a few seconds of interruption, a rolling restart behind a health-checked load balancer gives you most of the benefit. Pair it with backward-compatible migrations and you avoid maintaining a second full environment and a switch procedure that someone has to rehearse.
Blue-green also has a structural weakness. The switch is all-at-once, so a release that passes verification but fails under real traffic reaches every user at the same moment. Rollback is fast, but the blast radius is total. Teams often fix this by adding weighted routing to send 5% of traffic to green first. That turns blue-green into a canary release, and it brings back the problem blue-green was meant to avoid: two versions serving live requests at the same time, sharing sessions, caches and the database.
| Approach | User exposure | Rollback speed | Infrastructure cost | Database requirement |
|---|---|---|---|---|
| Blue-green | All users at once | Seconds (traffic switch) | Two full environments | Schema works with both versions |
| Rolling deploy | Grows as instances update | Minutes (redeploy old version) | Little or none extra | Schema works with both versions during rollout |
| Canary | Small slice first, then more | Fast (shift weight back) | Extra instances plus weighted routing | Schema works with both versions for the whole canary period |
| Feature flags | Chosen users or cohorts | Instant (toggle the flag) | Flag service plus code complexity | Schema supports both code paths while the flag exists |
None of these options removes the database constraint. Every one of them has a period where old code and new code, or old and new code paths, read and write the same data. Expand-and-contract migrations are therefore required whichever strategy you choose.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to blue green deployment monolith, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Reviewers see the exact diff and the list of affected services up front, so approval is a decision rather than an investigation.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- Per-service approve/reject means a bad shared value can be refused where it would break something, before it is live.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.