> ## 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. # Deploy 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 describes how to deploy and delete an instance of the [Migration Assistant](/docs/continuum/migration-assistant-overview) using the [Cloud Console](https://cockroachlabs.cloud) or the [Cloud API](/docs/cockroachcloud/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](/docs/continuum/migration-assistant-use). 3. Delete the instance when the migration is complete. The Assistant does not create or configure the target database cluster. Use the [Cloud Console](https://cockroachlabs.cloud) or [ccloud CLI](#prepare-the-target-cluster-with-ccloud) to create or identify a target cluster that meets the [Migration Assistant eligibility requirements](/docs/continuum/migration-assistant-overview#eligibility), and configure its IP allowlist before you deploy the Assistant. ## Prerequisites * Your source database and target cluster meet the [Migration Assistant eligibility requirements](/docs/continuum/migration-assistant-overview#eligibility). * For Console deployment, your Cockroach Cloud account must have the [Cluster Admin](/docs/cockroachcloud/authorization#cluster-admin) role on the target cluster or the [Organization Admin](/docs/cockroachcloud/authorization#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](/docs/cockroachcloud/ccloud-get-started). * For Cloud API deployment, create a Cloud API [service account and API key](/docs/cockroachcloud/managing-access). The service account must have the [Cluster Admin](/docs/cockroachcloud/authorization#cluster-admin) role on the target cluster or the [Organization Admin](/docs/cockroachcloud/authorization#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. 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. | ### 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](/docs/cockroachcloud/ccloud-reference). 1. Log in to the organization that contains the target cluster: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} ccloud auth login --org {organization-label} ``` 2. List the clusters in the organization: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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](/docs/cockroachcloud/ccloud-reference#create-a-new-cluster). 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: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} ccloud cluster networking allowlist create {cluster-name} {ip-address}/32 \ --name migration-assistant-access \ --sql \ --ui ``` 4. Verify the allowlist entry: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} ccloud cluster networking allowlist list {cluster-name} ``` For details, refer to [Create and manage IP allowlists with ccloud](/docs/cockroachcloud/ccloud-reference#create-and-manage-ip-allowlists). `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: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} { "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. ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} { "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](#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**](/docs/cockroachcloud/network-authorization#ip-allowlisting), 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](#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](/docs/continuum/migration-assistant-use). 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`](/docs/stable/select-clause) the data to migrate. ## Delete the instance When your migration is complete: 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. 1. Download any converted DDL, scripts, or reports you want to keep. 2. Delete the Assistant instance: ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} 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: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} { "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: ```json theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}} { "code": 5, "message": "migration assistant does not exist for this cluster", "details": [] } ``` ## See also * [Migration Assistant Overview](/docs/continuum/migration-assistant-overview) * [Use the Migration Assistant](/docs/continuum/migration-assistant-use)