A migration involves transfering 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 MOLT (Migrate Off Legacy Technology) toolkit to aid in migrations.
This page provides an overview of the following:
- Overall migration sequence
- MOLT tools
Migration sequence
A migration to CockroachDB generally follows this sequence:
- Assess and discover: Inventory the source database, flag unsupported features, make a migration plan.
- Prepare the environment: Configure networking, users and permissions, bucket locations, replication settings, and more.
- Convert the source schema: Generate CockroachDB-compatible DDL. Apply the converted schema to the target database. Drop constraints and indexes to facilitate data load.
- Load data into CockroachDB: Bulk load the source data into the CockroachDB cluster.
- Finalize target schema: Recreate indexes or constraints on CockroachDB that you previously dropped to facilitate data load.
- (Optional) Replicate ongoing changes: Keep CockroachDB in sync with the source. This may be necessary for migrations that minimize downtime.
- Stop application traffic: Limit user read/write traffic to the source database. This begins application downtime.
- Verify data consistency: Confirm that the CockroachDB data is consistent with the source.
- (Optional) Enable failback: Replicate data from the target back to the source, enabling a reversion to the source database in the event of migration failure.
- Cut over application traffic: Resume normal application use, with the CockroachDB cluster as the target database. This ends application downtime.
The MOLT (Migrate Off Legacy Technology) toolkit enables safe, minimal-downtime database migrations to CockroachDB. MOLT combines schema transformation, distributed data load, continuous replication, and row-level validation into a highly configurable workflow that adapts to diverse production environments.
MOLT tools
MOLT (Migrate Off Legacy Technology) 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.
| Tool | Usage | Tested and supported sources | Release status |
|---|---|---|---|
| Schema Conversion Tool | Schema conversion | PostgreSQL, MySQL, Oracle, SQL Server | GA (Cloud only) |
| Fetch | Initial data load | PostgreSQL 11-16, MySQL 5.7-8.0+, Oracle Database 19c (Enterprise Edition) and 21c (Express Edition), CockroachDB | GA |
| Replicator | Continuous replication | CockroachDB, PostgreSQL 11-16, MySQL 5.7+ and 8.0+, Oracle Database 19c+ | GA |
| Verify | Schema and data validation | PostgreSQL 12-16, MySQL 5.7-8.0+, Oracle Database 19c (Enterprise Edition) and 21c (Express Edition), CockroachDB | Preview |
For CockroachDB-to-CockroachDB migrations, contact your account team for guidance.
Schema Conversion Tool
The MOLT Schema Conversion Tool converts a source database schema to a CockroachDB-compatible schema. The tool performs the following actions:
- Identifies unimplemented features.
- Rewrites unsupported DDL syntax.
- Applies CockroachDB schema best practices.
Fetch
MOLT Fetch performs the initial data load to CockroachDB. It supports:
- Multiple migration flows via
IMPORT INTOorCOPY FROM. - Data movement via cloud storage, local file servers, or direct copy.
- Concurrent data export from multiple source tables and shards.
- Schema transformation rules.
- After exporting data with
IMPORT INTO, safe continuation to retry failed or interrupted tasks from specific checkpoints.
Replicator
MOLT Replicator provides continuous replication capabilities for minimal-downtime migrations. It supports:
- Continuous replication from source databases to CockroachDB.
- Multiple consistency modes for balancing throughput and transactional guarantees.
- Failback replication from CockroachDB back to source databases.
- Performance tuning for high-throughput workloads.
Verify
MOLT 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.
Migration granularity
You may choose to migrate all of your data into a CockroachDB cluster at once. However, for larger data stores it's recommended that you migrate data in separate phases. This can help break the migration down into manageable slices, and it can help limit the effects of migration difficulties.
Continuous replication
After data is migrated from the source into CockroachDB, you may choose to continue streaming changes to that source data from the source to the target. This is important for migrations that aim to minimize application downtime, as they may require the source database to continue receiving writes until application traffic is fully cut over to CockroachDB.
Data transformation strategy
If there are discrepencies between the source and target schemas, the rules that determine necessary data transformations need to be defined. These transformations can be applied in the source database, in flight, or in the target database.
Validation strategy
There are several different ways of verifying that the data in the source and the target match one another. You must decide what validation checks you want to perform, and when in the migration process you want to perform them.
Rollback plan
Until the migration is complete, migration failures may make you decide to roll back application traffic entirely to the source database. You may therefore need a way of keeping the source database up to date with new writes to the target. This is especially important for risk-averse migrations that aim to minimize downtime.
Cutover plan
Cutover is the process of switching application traffic from the source database to CockroachDB.
There are many different approaches to cutover. It can happen all at once, it can occur in multiple steps (in tandem with different migration phases). It's possible to cut over read and write traffic at different times. The possibilities are varied.
The decision of how to cut over application traffic is closely linked with many of the other choices above.
Learn more about the different migration variables, how you should consider the different options for each variable, and how to use the MOLT toolkit for each variable.
