> ## 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 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 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 [ccloud CLI](/docs/cockroachcloud/ccloud-get-started) to [create or identify a target cluster](#prepare-the-target-cluster-with-ccloud) 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). * 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). * 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. ## 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, [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. 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, use `ccloud cluster networking allowlist list {cluster-name}` to verify that the allowlist contains your network's current public IP address. If necessary, add the network as described in [Prepare the target cluster with ccloud](#prepare-the-target-cluster-with-ccloud). You can also add or update the network [in the Console under **Networking**](/docs/cockroachcloud/network-authorization#ip-allowlisting). 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. 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)