Handling MongoDB Schema Evolution in Production

Q: Handling MongoDB Schema Evolution in Production

Safe schema evolution in MongoDB follows an **expand–migrate–contract** cycle. **Expand**: writers emit both old and new field names and readers accept either, so services can deploy independently. **Migrate**: a background job backfills old documents to the new shape at a throttled rate, and a `$jsonSchema` validator enforces new writes. **Contract**: once every reader is on the new shape and backfill is complete, remove old-field handling and tighten validation. A `schemaVersion` field on every document makes the state of migration observable. The risks to manage are **service-deployment ordering**, **rollback safety**, and **long-tail legacy documents** — all of which the expand–contract cycle absorbs cleanly.

Intermediate·2 min read·

MongodbHubspotZendeskTwilioCloudflare

Fast recall

Quick revision

Core answer

Safe schema evolution in MongoDB follows an expand–migrate–contract cycle. Expand: writers emit both old and new field names and readers accept either, so services can deploy independently. Migrate: a background job backfills old documents to the new shape at a throttled rate, and a $jsonSchema validator enforces new writes. Contract: once every reader is on the new shape and backfill is complete, remove old-field handling and tighten validation. A schemaVersion field on every document makes the state of migration observable. The risks to manage are service-deployment ordering, rollback safety, and long-tail legacy documents — all of which the expand–contract cycle absorbs cleanly.

Interview-ready guide

Interview answer

State the pattern

Expand–Migrate–Contract is the canonical zero-downtime schema change
Every document tagged with schemaVersion

Walk the phases

Expand: writers emit both old and new fields; readers accept either; services deploy independently
Migrate: throttled backfill rewrites old docs; $jsonSchema validator in moderate mode enforces new writes
Contract: once backfill = 0, remove old output from writers, then old reads, then tighten validator to strict

Call out the risks

Downstream consumers (search, warehouse) need their own dual-handling
Validator too strict too early breaks legacy reads
Change streams with resumable tokens for consumer sync

Close

Rollback is flipping a flag, not restoring a backup
The pattern is worth days of slow ramp for zero-downtime safety

03 · Deep dive