> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cockroachlabs.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Use the Migration Assistant
**This feature is in [preview](/docs/releases/cockroachdb-feature-availability)** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com).
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](/docs/continuum/migration-assistant-overview#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](/docs/continuum/migration-assistant-overview).
Generated commands and downloaded scripts can contain database connection strings and credentials. Store them securely, and do not copy them into tickets, chat, or public logs.
## Prerequisites
* Complete the instructions in [Deploy the Migration Assistant](/docs/continuum/migration-assistant-deploy), including target cluster setup.
* Have a connection string for a source database that meets the [Migration Assistant eligibility requirements](/docs/continuum/migration-assistant-overview#eligibility). The database must be running and reachable from CockroachDB Cloud, and the connection user must be able to read the schema catalog and [`SELECT`](/docs/stable/select-clause) 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](/docs/continuum/migration-assistant-deploy).
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`](/docs/stable/select-clause) 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](/docs/continuum/migration-assistant-overview#what-is-shared-with-the-migration-agent).
4. Click **Save selection**, and then continue to schema conversion.
You can migrate a subset of the source's schemas or databases per run. To migrate a large source, split it into several migrations and run them sequentially.
## 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.
Executable DDL is not necessarily behaviorally equivalent to the source schema. Review application behavior, constraints, and data modeling for every lossy substitution.
## 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](/docs/molt/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](/docs/continuum/migration-assistant-overview#postgresql-compatibility).
A successful target-only test does not establish source and target behavioral equivalence. Review generated tests carefully, and test migrated application behavior separately.
## 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](/docs/molt/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](/docs/continuum/migration-assistant-overview#postgresql-compatibility).
5. Run basic application tests against the target using the application's database user, including checks of its access permissions.
For a low-downtime migration, configure ongoing replication with [MOLT Replicator](/docs/molt/molt-replicator) and plan the application cutover separately. The Migration Assistant does not run ongoing replication or perform application cutover.
## 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](/docs/molt/migration-strategy#test-query-results-and-performance) and [rehearse the production cutover](/docs/molt/migration-strategy#perform-a-dry-run).
For a low-downtime migration, configure ongoing replication with [MOLT Replicator](/docs/molt/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](/docs/molt/molt-fetch) scripts from data load for offline review.
## See also
* [Delete the Migration Assistant instance](/docs/continuum/migration-assistant-deploy#delete-the-instance)
* [Configure MOLT Replicator for ongoing replication](/docs/molt/molt-replicator)