Skip to main content
This feature is in preview and subject to change. To share feedback and/or issues, contact Support.
Moving data from an existing database is often the largest step in adopting a new platform. Migration Assistant is Cockroach Continuum’s AI-guided workflow for moving from an existing PostgreSQL database onto CockroachDB: it guides you through connecting a source database, converting its schema, loading and verifying data, and planning your next steps. The Assistant explains its work and lets you review and edit generated statements before you apply them. This page explains what the Migration Assistant is and how it works at a high level. For instructions on deploying it, refer to Deploy the Migration Assistant. For instructions on using it to move your data, refer to Use the Migration Assistant.

​
Eligibility

The Migration Assistant is available in open preview, with no organization enrollment required. Your source database and target cluster must meet the following requirements:
  • The source database runs PostgreSQL 15 to 18.
  • The target is an existing, single-region Mission Critical cluster in a Cockroach Continuum organization or an existing, single-region CockroachDB Advanced cluster in another CockroachDB Cloud organization.
  • The target cluster does not already have a Migration Assistant instance. Each target cluster can have one instance at a time.
CockroachDB Basic, CockroachDB Standard, CockroachDB BYOC, CockroachDB self-hosted, and multi-region target clusters are not supported in the Migration Assistant preview. Azure target clusters are not currently supported.

​
PostgreSQL compatibility

Support for a PostgreSQL source version does not mean that every feature used by the source database can be migrated automatically. Review the converted schema and migration plan for unsupported objects and changes that affect application behavior. The Migration Assistant reports which objects cannot be converted and require manual work. The following limitations apply during preview: For broader differences between PostgreSQL and CockroachDB, refer to PostgreSQL Compatibility. CockroachDB support for a feature does not by itself mean that the Migration Assistant migrates it automatically.

​
How it works

You deploy the Migration Assistant to CockroachDB Cloud. There is nothing to install locally. The Assistant uses the MOLT (Migrate Off Legacy Technology) toolset for conversion, data load, and verification. You can download converted DDL and generated scripts. During the migration, you can ask the Migration agent questions about your schema and the conversion in a chat panel. The Migration agent may suggest updates to your schema, stored procedures, and user-defined functions, which you can choose whether to apply. For more information, refer to Ask questions in the Migration agent panel.

​
Migration sequence

The Assistant guides you through the following migration sequence.
  1. Connect and verify. In this step the Assistant connects to the source database and verifies read permissions. It also connects to the target database and verifies write permissions.
  2. Select what to migrate. The Assistant discovers the source schema, and you select the objects to migrate.
  3. Convert the schema. The Assistant converts the source schema to CockroachDB DDL, explains each change it makes, and calls out anything that needs your decision. You can edit any statement before applying it.
  4. Generate the plan. The Assistant assesses the selected objects and schema-conversion decisions, then produces an ordered migration plan.
  5. Complete pre-migration work. You review and complete the executable and manual steps required to prepare the target for loading data.
  6. Load data. The Assistant moves the source data into the target cluster, using MOLT Fetch.
  7. Convert and test routines. The Assistant classifies and converts source stored procedures and user-defined functions (UDFs), and generates tests for your review.
  8. Complete post-migration work. You restore deferred database objects including indexes and foreign keys, and verify loaded data with MOLT Verify. Later, outside the Migration Assistant, you will test the application against the target.
  9. Review results. The Assistant summarizes the migration, identifies objects that still require manual work, and recommends next steps.
For more information about the migration sequence, refer to Use the Migration Assistant.
The Assistant does not run ongoing replication or perform application cutover. Its scope ends at a converted, loaded, and verified target. For ongoing replication, refer to MOLT Replicator. For application validation and cutover preparation, refer to Migration Best Practices.

​
What is shared with the Migration agent

The Migration agent is the AI component of the Migration Assistant. Cockroach Labs manages the Migration agent in its own cloud account, so you do not need to configure or connect a separate AI service. Your database credentials stay with the Migration Assistant and are never shared with the Migration agent. To analyze compatibility and generate a migration plan, the Assistant shares the following information with the Migration agent:
  • Schema structure and definitions, including object DDL for tables, views, types, and routines.
  • Limited table statistics, such as row counts, that help determine how to group tables in MOLT Fetch commands.
  • Text that you enter in the Migration agent panel.
The Assistant tokenizes schema identifiers by default. Tokenization obfuscates names by replacing database, schema, table, column, type, routine, and routine-variable names with generated identifiers before schema content is shared with the Migration agent. The Tokenization tab previews what will be shared and lets you inspect the generated mappings. Database row data is never shared with the Migration agent. It moves only between the source database, target database, and customer-controlled storage.

​
Demo video

For a demonstration of how to use the Migration Assistant, watch the following video:

​
See also