Deploy the Migration Assistant

1. Create a Migration Assistant instance for an eligible target cluster using the 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.

​

Prerequisites

• Your source database and target cluster meet the Migration Assistant eligibility requirements.
• Install ccloud and log in to the organization that contains the target cluster. Refer to Get Started with the ccloud CLI.
• 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.

​

Prepare the target cluster with ccloud

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.

​

Create a Migration Assistant instance

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.

​

Access the Assistant

1. 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.

​

Connect your source and target

• 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

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"
   }
   

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

​

See also

• Migration Assistant Overview
• Use the Migration Assistant