Couchbase Migration Execution

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

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

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:

What this skill won't help with

• Designing the target model — see couchbase-data-modeling for that. This skill assumes the target model is decided
• Sizing the target cluster — see couchbase-sizing. Migrations need correctly-sized target clusters; this skill assumes that's done
• Operating the cluster — see couchbase-mcp. Bucket / index / user creation on the target happens via that skill
• Application code that uses Couchbase — see couchbase-app-integration. The dual-write phase needs application code; this skill references the patterns but the SDK details live there
• Couchbase Mobile / Sync Gateway migrations — different product; out of scope

Hand off explicitly when the conversation crosses these lines.

A typical migration timeline

For a moderate-size migration (10-100 GB), expect roughly:

Total: 8-16 weeks for non-trivial production migrations. Big-bang migrations on small datasets can compress to days; large active-active dual-write migrations can stretch to months.

Don't surprise the user with this timeline — set the expectation up front. Migration projects that get "we'll be done by Friday" framing fail.

Quick decision tree

• Downtime allowed, small data, no live system? → Big-bang with cbimport
• Multi-domain app, can do it in slices? → Phased / strangler-fig pattern
• Live system, zero downtime, can modify app? → Dual-write
• Live system, zero downtime, can't modify app? → CDC-based (Debezium, AWS DMS, etc.)
• Source is MongoDB or DynamoDB? → Document-to-document; tooling does most of the lift
• Source is relational? → Modeling change required; ETL code or careful CDC transformation
• Unsure where to start? → Read strategies.md and answer the five-question checklist

Related skills

• couchbase-data-modeling — the modeling transformation that often accompanies migration
• couchbase-sizing — sizing the target cluster before data starts moving
• couchbase-app-integration — writing the dual-write layer in application code
• couchbase-mcp — creating the target bucket/scope/collection and running validation queries