Atlas: cut the app over to a new cluster with zero downtime

Not specified by the original author.

TL;DR: Migrations, restores, and tier changes all end in a connection string cutover. Do it with a rolling deploy and keep the old cluster until the new one proves itself. Verify on the new cluster: writes landing, reads correct, latency normal, no auth or pool errors in logs. Keep the old cluster for the retention window (days, not hours).

The fix

1. Get the new cluster fully ready and verified first: data counts, indexes, app smoke tests against it from staging. The cutover is not the time to discover a missing index.
2. Put the new connection string in the secret manager / env config, but do not activate it yet.
3. Freeze or drain writes briefly if the migration needs a final sync (live migration cutover does this anyway).
4. Rolling deploy: restart app instances so they pick up the new string a few at a time. Watch error rates and the new cluster's Connections metric climb while the old one drains.
5. Verify on the new cluster: writes landing, reads correct, latency normal, no auth or pool errors in logs.
6. Keep the old cluster for the retention window (days, not hours). Then decommission.
7. Never cut every instance at once. A bad string everywhere is a full outage; a bad string on 10% of instances is a rollback.
8. Feature-flag the connection string if your platform supports it, so cutover is a flag flip, not a deploy.
9. DNS-based cutover (CNAME swap) works but respects TTLs; prefer env-based rolling restarts for precision.
10. Have the rollback ready before you start: the old string, still valid, one deploy away.

When to use this

• This covers exactly what the title says: Atlas.
• You are setting this up for the first time, or auditing an existing setup.
• You want the key gotchas in one place before you start.

When not to use this

• You are doing a different workflow with Atlas; these steps are specific to the title above.
• You need the full reference docs; this is the short path, not the manual.

Compatibility

• Not pinned to a specific version; follows current Atlas behavior.

Cutover practices follow the Atlas live migration and restore verification guidance per https://www.mongodb.com/docs/atlas/import/live-migration-comparison-modes/ and https://www.mongodb.com/docs/atlas/backup/cloud-backup/restore-from-snapshot/, verified 2026-09-26.