> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Migration Overview

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

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 <InternalLink version="releases" path="molt">MOLT (Migrate Off Legacy Technology)</InternalLink> toolkit to aid in migrations.

This page provides an overview of the following:

* The generic [migration sequence](#migration-sequence)
* [MOLT tools](#molt-tools)
* [Variables](#migration-variables) to consider when choosing a migration approach
* [Common migration approaches](#common-migration-approaches)

## 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 <InternalLink version="stable" path="sql-statements#data-definition-statements">DDL</InternalLink>. 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](#migration-variables). The [common migration approaches](#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.

<img src="https://mintcdn.com/cockroachlabs/mEy4bzaxzRbvNkMw/images/molt/molt_flow_generic.svg?fit=max&auto=format&n=mEy4bzaxzRbvNkMw&q=85&s=e9603acea55b6228aa58a177810b07d3" alt="MOLT toolkit flow" style={{ maxWidth: "100%", display: "block", marginLeft: "auto", marginRight: "auto" }} width="337" height="391" data-path="images/molt/molt_flow_generic.svg" />

## MOLT tools

<InternalLink version="releases" path="molt">MOLT (Migrate Off Legacy Technology)</InternalLink> 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](#fetch), [Replicator](#replicator), and [Verify](#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-tool) | Schema conversion          | PostgreSQL, MySQL, Oracle, SQL Server                                                                            | GA (Cloud only)                                                                                 |
| [**Fetch**](#fetch)                                   | Initial data load          | PostgreSQL 11-16, MySQL 5.7-8.4, Oracle Database 19c (Enterprise Edition) and 21c (Express Edition)              | GA                                                                                              |
| [**Replicator**](#replicator)                         | Continuous replication     | PostgreSQL 11-16, MySQL 5.7-8.4, Oracle Database 19c+, CockroachDB                                               | GA                                                                                              |
| [**Verify**](#verify)                                 | Schema and data validation | PostgreSQL 12-16, MySQL 5.7-8.4, Oracle Database 19c (Enterprise Edition) and 21c (Express Edition), CockroachDB | <InternalLink version="releases" path="cockroachdb-feature-availability">Preview</InternalLink> |

<Note>
  For CockroachDB-to-CockroachDB migrations, contact your account team for guidance.
</Note>

### Schema Conversion Tool

The <InternalLink version="cockroachcloud" path="migrations-page">MOLT Schema Conversion Tool</InternalLink> converts a source database schema to a CockroachDB-compatible schema. The tool performs the following actions:

* Identifies <InternalLink path="migration-strategy#unimplemented-features-and-syntax-incompatibilities">unimplemented features</InternalLink>.
* Rewrites unsupported <InternalLink version="stable" path="sql-statements#data-definition-statements">DDL syntax</InternalLink>.
* Applies CockroachDB <InternalLink path="migration-strategy#schema-design-best-practices">schema best practices</InternalLink>.

### Fetch

<InternalLink path="molt-fetch">MOLT Fetch</InternalLink> performs the initial data load to CockroachDB. It supports:

* Multiple migration flows via `IMPORT INTO` or `COPY FROM`.
* Data movement via <InternalLink path="molt-fetch">cloud storage, local file servers, or direct copy</InternalLink>.
* <InternalLink path="molt-fetch-best-practices">Concurrent data export</InternalLink> from multiple source tables and shards.
* <InternalLink path="molt-fetch">Schema transformation rules</InternalLink>.
* After exporting data with `IMPORT INTO`, safe <InternalLink path="molt-fetch">continuation</InternalLink> to retry failed or interrupted tasks from specific checkpoints.

### Replicator

<InternalLink path="molt-replicator">MOLT Replicator</InternalLink> provides <InternalLink path="migration-considerations-replication">continuous replication</InternalLink> capabilities for minimal-downtime migrations. It supports:

* Continuous replication from source databases to CockroachDB.
* <InternalLink path="molt-replicator#consistency-modes">Multiple consistency modes</InternalLink> for balancing throughput and transactional guarantees.
* Failback replication from CockroachDB back to source databases.
* <InternalLink path="molt-replicator-best-practices#optimize-performance">Performance tuning</InternalLink> for high-throughput workloads.
* <InternalLink path="userscript-overview">Userscripts</InternalLink> for defining data transformations.

### Verify

<InternalLink path="molt-verify">MOLT Verify</InternalLink> 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](#molt-tools).

| Variable                                                                                                     | Description                                                                                                                                                 |
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <InternalLink path="migration-considerations-granularity">**Migration granularity**</InternalLink>           | Do you want to migrate all of your data at once, or do you want to split your data up into phases and migrate one phase at a time?                          |
| <InternalLink path="migration-considerations-replication">**Continuous replication**</InternalLink>          | After the initial data load (or after the initial load of each phase), do you want to stream further changes to that data from the source to the target?    |
| <InternalLink path="migration-considerations-transformation">**Data transformation strategy**</InternalLink> | If there are discrepancies between the source and target schema, how will you define those data transformations, and when will those transformations occur? |
| <InternalLink path="migration-considerations-validation">**Validation strategy**</InternalLink>              | How and when will you verify that the data in CockroachDB matches the source database?                                                                      |
| <InternalLink path="migration-considerations-rollback">**Rollback plan**</InternalLink>                      | What approach will you use to roll back the migration if issues arise during or after cutover?                                                              |

<InternalLink path="migration-considerations">Learn more about the different migration variables</InternalLink>, 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 <InternalLink path="molt-fetch">MOLT Fetch</InternalLink> for data loading and <InternalLink path="molt-replicator">MOLT Replicator</InternalLink> for ongoing replication. These common approaches are variants of the general [migration sequence](#migration-sequence).

| Migration approach                                                                                                            | Description                                                                                                                                                    | Best for                                                |
| ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| <InternalLink path="migration-approach-classic-bulk-load">Classic Bulk Load Migration</InternalLink>                          | Perform a one-time bulk load of source data into CockroachDB.                                                                                                  | Simple migrations with planned downtime.                |
| <InternalLink path="migration-approach-phased-bulk-load">Phased Bulk Load Migration</InternalLink>                            | Divide your data into separate phases and bulk load each phase.                                                                                                | Larger migrations with planned downtime per phase.      |
| <InternalLink path="migration-approach-delta">Delta Migration</InternalLink>                                                  | Perform an initial data load, then replicate ongoing changes continuously.                                                                                     | Minimal-downtime migrations.                            |
| <InternalLink path="migration-approach-phased-delta-failback">Phased Delta Migration with Failback Replication</InternalLink> | Divide your data into separate phases. For each phase, perform an initial data load, then replicate ongoing changes continuously. Enable failback replication. | Risk-averse migrations with minimal downtime per phase. |

Each of these approaches has a detailed walkthrough guide for performing these migrations using the [MOLT toolkit](#molt-tools). 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

* <InternalLink path="migration-strategy">Migration Best Practices</InternalLink>
* <InternalLink version="releases" path="molt">MOLT Releases</InternalLink>
* <InternalLink path="migration-considerations">Migration Considerations</InternalLink>
* <InternalLink path="migration-approach-classic-bulk-load">Classic Bulk Load Migration</InternalLink>
* <InternalLink path="molt-fetch">MOLT Fetch</InternalLink>
* <InternalLink path="molt-replicator">MOLT Replicator</InternalLink>