Skip to main content
A migration involves transferring data from a pre-existing source database onto a target CockroachDB cluster. Migrating data is a complex, multi-step process, and a data migration can take many different forms depending on your specific business and technical constraints. Cockroach Labs provides a toolkit to aid in migrations. This page provides an overview of the following:

​
Migration sequence

A migration to CockroachDB generally follows a variant of this sequence:
  1. Assess and discover: Inventory the source database, flag unsupported features, make a migration plan.
  2. Prepare the environment: Configure networking, users and permissions, bucket locations, and replication settings.
  3. Convert the source schema: Generate CockroachDB-compatible . Apply the converted schema to the target database. Drop constraints and indexes to facilitate data load.
  4. Load data into CockroachDB: Bulk load the source data into the CockroachDB cluster.
  5. Finalize target schema: Recreate indexes or constraints on CockroachDB that you previously dropped to facilitate data load.
  6. Replicate ongoing changes (optional): Keep CockroachDB in sync with the source. This may be necessary for migrations that minimize downtime.
  7. Stop application traffic: Limit user read/write traffic to the source database. This begins application downtime.
  8. Verify data consistency: Confirm that the CockroachDB data is consistent with the source.
  9. Enable failback (optional): Replicate data from the target back to the source, enabling a reversion to the source database in the event of migration failure.
  10. Cut over application traffic: Resume normal application use, with the CockroachDB cluster as the target database. This ends application downtime.
This sequence can vary depending on the needs on how your organization considers the migration variables. The common migration approaches describe some standard use cases, but even these may need to be modified to suit the needs of your migration. The following diagram shows how the MOLT (Migrate Off Legacy Technology) toolkit is used at various stages of the migration sequence. MOLT toolkit flow

​
MOLT tools

is a set of tools for schema conversion, data load, replication, and validation. Migrations with MOLT are resilient, restartable, and scalable to large data sets. MOLT Fetch, Replicator, and Verify are CLI-based to maximize control, automation, and visibility during the data load and replication stages.
For CockroachDB-to-CockroachDB migrations, contact your account team for guidance.

​
Schema Conversion Tool

The converts a source database schema to a CockroachDB-compatible schema. The tool performs the following actions:
  • Identifies .
  • Rewrites unsupported .
  • Applies CockroachDB .

​
Fetch

performs the initial data load to CockroachDB. It supports:
  • Multiple migration flows via IMPORT INTO or COPY FROM.
  • Data movement via .
  • from multiple source tables and shards.
  • .
  • After exporting data with IMPORT INTO, safe to retry failed or interrupted tasks from specific checkpoints.

​
Replicator

provides capabilities for minimal-downtime migrations. It supports:
  • Continuous replication from source databases to CockroachDB.
  • for balancing throughput and transactional guarantees.
  • Failback replication from CockroachDB back to source databases.
  • for high-throughput workloads.
  • for defining data transformations.

​
Verify

checks for data and schema discrepancies between the source database and CockroachDB. It performs the following verifications:
  • Table structure.
  • Column definition.
  • Row-level data.

​
Migration variables

You must decide how you want your migration to handle each of the following variables. These decisions will depend on your specific business and technical considerations. The MOLT toolkit supports any set of decisions made for the supported source databases. , how you should consider the different options for each variable, and how to use the MOLT toolkit for each variable.

​
Common migration approaches

MOLT supports various migration flows using for data loading and for ongoing replication. These common approaches are variants of the general migration sequence. Each of these approaches has a detailed walkthrough guide for performing these migrations using the MOLT toolkit. While these approaches are among the most common, you may need to modify these instructions to suit the specific needs of your migration.

​
See also