/couchbase-migration-execution

name: couchbase-migration-execution
description: "Execute data migrations into Couchbase from MongoDB, PostgreSQL, MySQL, Oracle, SQL Server, DynamoDB, Cassandra, files, or custom sources. Use whenever the user asks about migrating, migration strategy, dual-write, change data capture / CDC, Debezium, AWS DMS, big-bang vs phased migration, strangler-fig, cutover, rollback, cbimport, cbexport, cbtransfer, validation after migration, count parity, traffic switching, feature flags during migration, reconciliation between source and target, or 'how do I move my data from X to Couchbase.' Triggers on operational mechanics distinct from couchbase-data-modeling (modeling AFTER migration) — this skill is about actually MOVING the data, keeping source and target in sync during transition, validating equivalence, switching traffic, and rolling back if needed. Use proactively for migration planning, ETL pipeline design, dual-write patterns, CDC tool selection, cutover runbooks, and migration rollback decisions."
license: MIT

Couchbase migration execution

A skill for *executing* data migrations into Couchbase — the mechanics of moving data, keeping source and target in sync during transition, validating equivalence, and switching production traffic.

Distinct from the sibling skills:

• `couchbase-data-modeling` — how to MODEL the data after migrating (document shape, boundaries, access patterns)
• `couchbase-sizing` — how to size the target cluster
• `couchbase-app-integration` — how to write app code that uses Couchbase (relevant during dual-write)
• `couchbase-mcp` — operating the cluster (creating the target, running queries during validation)
• **`couchbase-migration-execution` (this skill)** — the operational mechanics of moving data and switching over

If the conversation is "how do I get my data from X into Couchbase," this is the right skill.

When this skill applies

• "How do I migrate from MongoDB / Postgres / DynamoDB / MySQL to Couchbase?"
• "Should I do a big-bang migration or phased?"
• "What's dual-write?"
• "How do I keep the source and target in sync during migration?"
• "Can I use CDC for this?"
• "How do I validate the migration worked?"
• "How do I cut over production traffic?"
• "What if the migration goes wrong — can I roll back?"
• "Tooling for bulk loading into Couchbase?"

Pick the right reference

| Question | Read | |---|---| | "Big-bang vs phased vs strangler-fig vs dual-write — which approach?" | `references/strategies.md` | | "What tools exist — cbimport, ETL frameworks, CDC tools?" | `references/tooling.md` | | "Migrating from MongoDB specifically" | `references/from-mongodb.md` | | "Migrating from PostgreSQL / MySQL / Oracle / SQL Server" | `references/from-relational.md` | | "Migrating from DynamoDB / Cassandra / files / something else" | `references/from-other-sources.md` | | "Dual-write code patterns, CDC setup, keeping source and target in sync" | `references/dual-write-and-cdc.md` | | "Validating the migration + cutting over + rolling back if needed" | `references/validation-and-cutover.md` |

The five-question pre-migration checklist

Before any data moves, get answers to these. Without them, migrations turn into multi-week troubleshooting sessions:

1. **What's the source?** Database type, version, total size, current write rate. Different sources have very different migration shapes 2. **Can the source go offline?** If yes (planned downtime acceptable): big-bang is on the table. If no: you need dual-write or CDC 3. **What's the modeling change?** Direct table-to-collection translation or a re-model? See `couchbase-data-modeling` skill — the answer here determines whether you can use simple bulk tools or need transformation code 4. **What's the rollback bar?** If something goes wrong post-cutover, can you tolerate going back to the source (probably yes for the first hour, probably no after a week)? 5. **What's the validation plan?** Count comparison? Sample comparison? Checksum? Automated test suite? Decide before starting

If the user hasn't thought through these, walk them through them before suggesting any specific approach.

The four migration approaches at a glance

| Approach | When it fits | Downtime | Complexity | Risk | |---|---|---|---|---| | **Big-bang** | Small data, planned downtime OK | Yes | Low | High (no rollback once cut over) | | **Phased / table-by-table** | Multi-domain app, can migrate one slice at a time | Per-slice downtime | Medium | Medium | | **Dual-write** | Need zero downtime, can modify app code | Zero | High | Low if done carefully | | **CDC-based** | Need zero downtime, can deploy CDC tooling | Zero | High but mechanical | Low if validated |

`strategies.md` covers each in detail with the decision framework.

Three principles for any migration

**Principle 1 — Validate at every step.** A migration is only as good as your confidence that source == target. Count comparison, sample comparison, and checksum verification at each step catch problems early. Defer validation to the end and a single bad transformation can corrupt everything.

**Principle 2 — Make the cutover reversible for as long as possible.** The first cutover should be: cut traffic to the new system, monitor for problems, cut back to source if needed. Keep source running in read-only mode for at least days, ideally weeks. The hardest migrations are the ones that decommissioned the source on day 1.

**Principle 3 — Migrations are projects, not commands.** Even "simple" migrations from MongoDB to Couchbase typically take weeks of work: test the tooling, dry-run on a sample, validate, do a partial migration in staging, validate, set up dual-write or CDC, run for a soak period, plan cutover, execute, monitor, decommission source. Don't let the user expect "I'll just run `cbimport` and we're done."

Common migration shapes

Recognize which shape the user is dealing with:

| Source | Typical shape | Reference | |---|---|---| | MongoDB → Couchba