playbooks

home / skills / shipshitdev / library / mongodb-migration-expert

mongodb-migration-expert skill

/bundles/infrastructure/skills/mongodb-migration-expert

This skill guides safe MongoDB schema changes and migrations with backward compatibility, batching backfills, and performance-conscious indexing.

npx playbooks add skill shipshitdev/library --skill mongodb-migration-expert

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
1.3 KB
---
name: mongodb-migration-expert
description: Database schema design, indexing, and migration guidance for MongoDB-based applications.
---

# MongoDB Migration Expert

You 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

Overview

This skill provides hands-on guidance for designing MongoDB schema changes, indexes, and migrations that are safe, observable, and backwards compatible. It focuses on additive-first migrations, batch backfills, and index design tuned to query patterns. The goal is to minimize downtime, avoid locking, and keep migrations idempotent.

How this skill works

I inspect your current schema, query patterns, and traffic characteristics to recommend migration steps that preserve compatibility. The process prescribes additive field changes, staged deployments that accept both old and new shapes, batch backfills, and post-backfill indexing adjustments. I also produce checklists and rollback/roll-forward plans so teams can execute safely and monitor progress.

When to use it

  • Adding or renaming fields on existing collections
  • Introducing new collections or multi-tenant patterns (tenantId)
  • Changing or adding indexes for performance
  • Planning zero-downtime or forward-only migrations
  • Designing schema for large datasets or high write throughput

Best practices

  • Make schema changes additive: add new fields or versions before removing old ones
  • Deploy app code that supports both old and new document shapes
  • Backfill data in measured, idempotent batches with progress monitoring
  • Create indexes after backfill when possible; match indexes to explain()-verified queries
  • Prefer compound indexes that begin with tenantId for multi-tenant collections
  • Document roll-forward and rollback procedures and test them on staging

Example use cases

  • Add a new address subdocument: add nullable fields, deploy dual-write handling, backfill in batches, then index common lookup fields
  • Switching primary identifier: introduce newId, write both ids during transition, migrate reads, backfill and deprecate oldId later
  • Improve query latency: analyze slow queries, create compound indexes matching filter+sort patterns, validate with explain, then monitor write impact
  • Introduce multi-tenancy: add tenantId to documents, update access code, add tenant-first compound indexes, and backfill tenant association for existing records

FAQ

How do I avoid long collection locks during migration?

Avoid operations that rebuild collections in-place. Use additive changes, backfill in small batches, and create indexes using background or rolling strategies when available.

When should I create indexes during migration?

Prefer creating indexes after backfill to avoid expensive index builds on partially populated fields. If queries need the index immediately, build it incrementally and monitor write impact.