Use the Migration Assistant

This page has instructions for using the Migration Assistant to move data from an existing PostgreSQL database onto CockroachDB. The steps on this page follow the migration sequence: they guide you through connecting a source database, converting its schema, loading and verifying data in the target database, and identifying the work that remains before cutover. Along the way, the Assistant explains its work and lets you review and edit generated statements before you apply them. It guides the migration, but you remain responsible for reviewing generated SQL and Migration agent suggestions, testing application behavior, and planning replication and cutover. You can ask questions in the Migration agent panel throughout the workflow. For more general information about the Migration Assistant, see the Migration Assistant Overview.

​

Prerequisites

• Complete the instructions in Deploy the Migration Assistant, including target cluster setup.
• Have a connection string for a source database that meets the Migration Assistant eligibility requirements. The database must be running and reachable from CockroachDB Cloud, and the connection user must be able to read the schema catalog and SELECT data.

​

Step 1. Connect and verify

When you first open the Assistant page, the target connection is prefilled with the CockroachDB cluster where you deployed the Assistant.

1. Review the data-handling notice on the Connect & verify page.
2. Enter the connection string for your source database. The source must be reachable from CockroachDB Cloud.
3. Verify that the prefilled target connection identifies the cluster where you deployed the Assistant.
4. Click Validate connections. The Assistant checks source connectivity, authentication, SELECT access, and version compatibility. It checks target connectivity, authentication, schema-changing privileges, and cluster health.
5. If a check fails, correct the connection details or network access and validate again. Continue only after both databases report that they are ready.

​

Step 2. Select objects

The Assistant discovers the source’s tables and routines.

1. On the Tables and Routines tabs, select the objects to migrate. You can search and filter the discovered objects.
2. Review objects that the Assistant reports as already existing on the target.
3. Review the tokenization settings. Tokenization obfuscates the names of schema objects before schema content is shared with the Migration agent. For details, refer to What is shared with the Migration agent.
4. Click Save selection, and then continue to schema conversion.

​

Step 3. Convert and review the schema

The Assistant converts the selected source schema to CockroachDB DDL. It separates statements that could not be converted from statements that contain valid but lossy substitutions.

1. Review the conversion summary, including every unconverted statement and lossy substitution.
2. Compare the source and target data definition language (DDL). Edit the target DDL when necessary, or download the converted DDL for offline review.
3. For an unconverted statement, click Ask AI to convert these to request a conversion and an explanation of its behavioral differences.
4. For grouped substitutions, click Ask AI about these to request an explanation of the changes and their application impact.
5. Apply a Migration agent suggestion only after confirming that its target DDL and data semantics are appropriate for your workload.
6. Continue after you have reviewed each conversion failure and lossy substitution and accounted for any required follow-up work.

​

Step 4. Generate and review the migration plan

The Assistant assesses the selected objects and your schema-conversion decisions, then generates an ordered migration plan.

1. Review the compatibility rating and the counts of pre-migration steps, table migrations, routine conversions, and post-migration steps.
2. Review the listed issues and warnings, and make note of any that will require a follow-up action.
3. Review warnings and plan notes, including the data-load mode, type conversions, foreign-key handling, source statistics, network and TLS requirements, and routines that require individual review.

​

Step 5. Complete pre-migration steps

The plan can contain required, optional, executable, and manual steps.

1. Review the entire list and expand each step to inspect its command or instructions.
2. For an executable step, review the generated command and click Execute.
3. Perform manual steps outside the Assistant.
4. Click Skip only when an optional step does not apply, or you have satisfied the prerequisite elsewhere.
5. Confirm that all required pre-migration steps are complete before continuing.

Pre-migration work can include creating the target database and schemas, applying converted table DDL, gathering source statistics, and generating a type-map file for edited column types.

​

Step 6. Load data

The Assistant generates and runs MOLT Fetch commands to move the selected data to the target cluster.

1. Review the generated scripts and the plan’s data-load mode before execution.
2. Click Execute for each table-migration batch and monitor the live MOLT output.
3. If a batch fails, review its output and the displayed recovery instructions before retrying it.
4. Confirm that every selected table has migrated before continuing.

Direct-copy batches require network connectivity from the Assistant to both databases and cannot resume in the middle of a batch.

​

Step 7. Review, create, and test routines

The Assistant classifies stored procedures and user-defined functions as direct copy, minor fix, assisted rewrite, or manual rewrite.

1. Review the classification, converted SQL, explanation, confidence, and risk factors for every routine.
2. Click Create all for direct-copy and minor-fix routines. Assisted and manual rewrites require individual decisions.
3. For an assisted rewrite, compare the source and converted SQL, edit the proposed SQL if necessary, and acknowledge its risks before creating it.
4. Review the generated tests before running them. Source execution requires explicit consent; otherwise, the Assistant tests only the target.
5. Compare source and target results when source testing is enabled.
6. Rewrite unsupported routines outside the Assistant, or skip them and record the required follow-up work.

If the source uses triggers, migrating their functions does not create the triggers themselves. After installing the functions, manually re-create the triggers supported by your target and test their behavior. Refer to PostgreSQL compatibility.

​

Step 8. Complete post-migration work

Post-migration steps restore database objects omitted for load performance and verify the migrated data.

1. Review every required and optional post-migration step.
2. After all data loads finish, execute the steps that recreate secondary indexes and deferred foreign keys.
3. Run MOLT Verify for every migrated schema and review the output for row-count or data mismatches.
4. Before application testing or cutover, manually configure the required users, roles, ownership, privileges, and row-level security on the target. The Assistant does not migrate this configuration; refer to PostgreSQL compatibility.
5. Run basic application tests against the target using the application’s database user, including checks of its access permissions.

​

Step 9. Review results and plan next steps

The Results page can mark the guided migration complete while still listing skipped or failed objects that require manual work.

1. Review the migration totals, source and target versions, duration, throughput, load mode, and verification status.
2. Review the source-execution audit and any high-risk acknowledgements.
3. Use Objects not migrated as the required work queue. Resolve each skipped or failed object.
4. Test application behavior affected by type substitutions or routine rewrites.
5. Test and optimize application queries and rehearse the production cutover.

For a low-downtime migration, configure ongoing replication with MOLT Replicator and plan the application cutover separately. The Assistant does not run ongoing replication or perform application cutover.

​

Ask questions in the Migration agent panel

Throughout the migration, you can ask the Assistant questions about your schema, conversion issues, and generated plan in the Migration agent panel. The panel groups the interaction history by migration stage. Treat its suggestions as proposals and review them before applying changes.

​

Results and downloads

The Assistant records migration activity and your acknowledgements of consequential actions. The Results page includes source-execution and high-risk acknowledgement information. You can also download converted DDL from schema conversion and generated MOLT Fetch scripts from data load for offline review.

​

See also

• Delete the Migration Assistant instance
• Configure MOLT Replicator for ongoing replication