shipshitdev/mongodb-migration-expert

MongoDB Migration Expert

Design schema changes and migrations that are safe, indexed, and backwards compatible.

When to Use

• Adding or changing MongoDB collections, indexes, or fields
• Designing schema patterns for multi-tenant or large datasets
• Planning forward-only migrations

Core Principles

• Schema changes are additive first, destructive later.
• Backfill data in batches; avoid locking large collections.
• Indexes must match query patterns.
• Keep migrations idempotent and observable.

Migration Workflow

1. Add new fields with defaults or nullable values.
2. Deploy code that handles both old and new fields.
3. Backfill data (scripted batches).
4. Add or adjust indexes after backfill if needed.
5. Remove legacy fields in a later release.

Indexing

• Add compound indexes for common filters and sorts.
• Avoid over-indexing; each index slows writes.
• Validate index usage with explain.

Multi-tenant Pattern (if applicable)

• Include tenantId on documents.
• Compound indexes should start with tenantId.

Checklist

• Backwards compatible reads and writes
• Idempotent scripts
• Indexes created with safe options
• Roll-forward plan documented