Deploy the Migration Assistant

This feature is in preview and subject to change. To share feedback and/or issues, contact Support.

This page describes how to deploy and delete an instance of the Migration Assistant using the Cloud Console or the Cloud API.

At a high level, you take the following steps:

1. Create a Migration Assistant instance for an eligible target cluster using the Console or Cloud API.
2. Use the instance to migrate your data, as described in Use the Migration Assistant.
3. Delete the instance when the migration is complete.

The Assistant does not create or configure the target database cluster. Use the Cloud Console or ccloud CLI to create or identify a target cluster that meets the Migration Assistant eligibility requirements, and configure its IP allowlist before you deploy the Assistant.

Prerequisites

• Your source database and target cluster meet the Migration Assistant eligibility requirements.
• For Console deployment, your Cockroach Cloud account must have the Cluster Admin role on the target cluster or the Organization Admin role in the organization.
• For Cloud API deployment, install ccloud and log in to the organization that contains the target cluster. Refer to Get Started with the ccloud CLI.
• For Cloud API deployment, create a Cloud API service account and API key. The service account must have the Cluster Admin role on the target cluster or the Organization Admin role in the organization. The key inherits the roles of the service account.
• Your PostgreSQL source database must be reachable over the network from CockroachDB Cloud.
• Know the public IP address or network CIDR that will access the Assistant’s web interface.

Create an instance

Create the instance in the Cloud Console or by calling the Cloud API.

Console

1. Log in to the Cloud Console and select the organization that contains the target cluster.
2. On the target cluster’s Networking page, add your network to the IP allowlist.
3. In the left navigation, click Migrations, then click New migration.
4. Select the Target cluster. The target must meet the eligibility requirements.
5. Review the Region. For a single-region cluster, the region is preselected. For a multi-region cluster, select the region where the Assistant runs. You cannot change the region later; to move the Assistant, delete the instance and create it again.
6. Click Continue. The instance appears with status Deploying. The page updates automatically; provisioning typically takes 10 to 20 minutes.
7. When the status is Ready, continue to Access the Assistant.

The Status column has the following values:

Status	Description
Deploying	The instance is provisioning.
Ready	The instance is running and responding. Open assistant is available from the Actions menu.
Unavailable	The instance is running but not responding. The page keeps checking and updates the status when the instance responds.
Unknown	The instance is running, but its health could not be checked. The page keeps checking and updates the status.
Failed	Provisioning failed. The error appears below the status. After addressing its cause, click Retry deploy, which creates the instance again in the same region.
Deleting	The instance is being torn down after a delete request.

Cloud API

Prepare the target cluster with ccloud

Use ccloud to prepare the target cluster. For complete command syntax and options, refer to the ccloud CLI Command Reference.

1. Log in to the organization that contains the target cluster:

   ccloud auth login --org {organization-label}
   

2. List the clusters in the organization:

   ccloud cluster list
   

   The output includes each cluster’s name, ID, plan, and state. Select an existing eligible target and record both its name and ID. ccloud commands identify the cluster by name; the Migration Assistant API identifies it by ID.

   If you need to create an Advanced target cluster, use ccloud cluster create. Replace the placeholders with a supported cloud, region, node count, and cluster size:

   ccloud cluster create ADVANCED {cluster-name} {region}:{node-count} \
     --cloud {cloud-provider} \
     --vcpus {vcpus-per-node} \
     --storage-gib {storage-gib-per-node}
   

   For additional creation options, refer to Create a new cluster with ccloud.

3. Add the network that will access the Assistant to the target cluster’s IP allowlist. For a single public IP address, use a /32 CIDR:

   ccloud cluster networking allowlist create {cluster-name} {ip-address}/32 \
     --name migration-assistant-access \
     --sql \
     --ui
   

4. Verify the allowlist entry:

   ccloud cluster networking allowlist list {cluster-name}
   

   For details, refer to Create and manage IP allowlists with ccloud.

ccloud does not currently expose the Migration Assistant endpoint. Use the target cluster ID from ccloud cluster list with the Cloud API in the following steps.

Create a Migration Assistant instance

To manage the instance, use the cluster’s migration-assistant endpoint in the Cloud API. In the following examples, replace {cluster_id} with the cluster ID returned by ccloud cluster list, and replace {secret_key} with the API key of your service account.

1. Create the instance:

   curl --request POST \
     --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant' \
     --header 'Authorization: Bearer {secret_key}' \
     --header 'Content-Type: application/json' \
     --data '{}'
   

   The optional region field specifies the Assistant’s deployment region. If omitted, the service selects a default region.

   The call returns immediately with status PENDING while the control plane provisions the instance in the background:

   {
     "id": "f83ef76b-0e72-4a40-bbcf-a3d6188726f5",
     "cluster_id": "c061d097-84b3-4d49-b280-2f579e4a18cb",
     "deployed_region": "us-east1",
     "status": "PENDING",
     "url": "",
     "last_error": "",
     "created_at": "2026-08-07T17:37:31.235157Z",
     "updated_at": "2026-08-07T17:37:31.235157Z",
     "username": "",
     "password": "",
     "bucket_grantee": "",
     "health": "NOT_COMPUTED"
   }
   

2. Poll the same endpoint every 60 seconds until the status is RUNNING. Provisioning typically takes 10 to 20 minutes, because it creates a dedicated node pool and boots the Assistant.

   curl --request GET \
     --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant' \
     --header 'Authorization: Bearer {secret_key}'
   

   When provisioning completes, the response includes the URL for the Assistant’s web interface. The Assistant uses Cockroach Cloud single sign-on (SSO), so the username and password fields are empty:

   {
     "id": "f83ef76b-0e72-4a40-bbcf-a3d6188726f5",
     "cluster_id": "c061d097-84b3-4d49-b280-2f579e4a18cb",
     "deployed_region": "us-east1",
     "status": "RUNNING",
     "url": "https://molt-ai.{generated_id}.crdb.io/",
     "last_error": "",
     "created_at": "2026-08-07T17:37:31.235157Z",
     "updated_at": "2026-08-07T17:40:26.406841Z",
     "username": "",
     "password": "",
     "bucket_grantee": "{bucket_grantee}",
     "health": "HEALTHY"
   }
   

   The url contains a generated hostname in the molt-ai subdomain, such as https://molt-ai.bpnk.crdb.io/.

   bucket_grantee identifies the cloud identity to grant access to your bucket when using optional cloud-storage loading. At launch, this option supports Google Cloud Storage only, and both the target cluster and bucket must be on Google Cloud.

3. Record the url from the RUNNING response.

The status field has the following values:

Status	Description
PENDING	The instance is provisioning. The url is empty.
RUNNING	The instance is ready. The response includes the url for the Assistant’s web interface.
FAILED	Provisioning failed. The last_error field reports the cause. To retry, send the create request again. The instance is retried in place in the same region. To change the region, delete the instance and create it again.
DELETING	The instance is being torn down after a delete request.

Each instance is dedicated to your migration. It runs on isolated capacity alongside your cluster, with its own TLS certificate, and is separate from the infrastructure running the cluster itself.

Access the Assistant

1. In the Console, go to Migrations. For the target cluster with status Ready, open the Actions menu and select Open assistant. The Assistant opens in a new tab. If you use the Cloud API, open the url from the RUNNING response in a browser.
2. Sign in with your Cockroach Cloud account. You must be a member of the target cluster’s organization.

The Assistant instance serves only your migration, and is reachable only from networks on the cluster’s IP allowlist. If the URL times out, verify that the allowlist contains your network’s current public IP address in the Console under Networking, or use ccloud cluster networking allowlist list {cluster-name}. If necessary, add or update the network in the Console or as described in Prepare the target cluster with ccloud.

After you add or update an allowlist entry, the change can take a few minutes to propagate to the Assistant.

Connect your source and target

In the Assistant, connect your source database and run the connectivity check before starting the migration stages. Refer to Use the Migration Assistant.

Because the Assistant runs in CockroachDB Cloud, your source database must be reachable from CockroachDB Cloud, not only from your workstation:

• The source needs a routable endpoint: a public hostname or IP address, or a private connection path. A database bound to localhost, or reachable only over your VPN, does not work.
• Your network and firewall rules must allow inbound connections from the Assistant on the database port.
• The connection credentials must be able to read the source’s schema catalog and SELECT the data to migrate.

Delete the instance

When your migration is complete:

Console

1. Download any converted DDL, scripts, or reports you want to keep.
2. In the Console, go to Migrations. For the target cluster, open the Actions menu and select Delete migration.
3. In the confirmation dialog, click Delete. The row shows Deleting until the instance is removed.

Deleting the Assistant stops any migration in progress and releases its dedicated compute. Deletion is available once deployment completes or fails.

Cloud API

1. Download any converted DDL, scripts, or reports you want to keep.

2. Delete the Assistant instance:

   curl --request DELETE \
     --url 'https://cockroachlabs.cloud/api/v1/clusters/{cluster_id}/migration-assistant' \
     --header 'Authorization: Bearer {secret_key}'
   

   The response shows DELETING while teardown is in progress:

   {
     "id": "f83ef76b-0e72-4a40-bbcf-a3d6188726f5",
     "cluster_id": "c061d097-84b3-4d49-b280-2f579e4a18cb",
     "deployed_region": "us-east1",
     "status": "DELETING",
     "url": "",
     "last_error": "",
     "created_at": "2026-08-07T17:37:31.235157Z",
     "updated_at": "2026-08-07T17:58:08.947081Z",
     "username": "",
     "password": "",
     "bucket_grantee": "",
     "health": "NOT_COMPUTED"
   }
   

When teardown completes, the endpoint reports that no Assistant exists for the cluster:

{
  "code": 5,
  "message": "migration assistant does not exist for this cluster",
  "details": []
}

See also

• Migration Assistant Overview
• Use the Migration Assistant