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

# Virtual Clusters

export const InternalLink = ({version, path = "", children, ...props}) => {
  let detectedVersion = version || "stable";
  if (typeof window !== 'undefined' && !version) {
    const match = window.location.pathname.match(/\/docs\/([^/]+)/);
    if (match) {
      detectedVersion = match[1];
    }
  }
  const normalizedPath = path.startsWith("/") ? path.slice(1) : path;
  return <a href={`/docs/${detectedVersion}/${normalizedPath}`} {...props}>
      {children}
    </a>;
};

<Note>
  **This feature is in <InternalLink version="releases" path="cockroachdb-feature-availability">preview</InternalLink>** and subject to change. To share feedback and/or issues, contact [Support](https://support.cockroachlabs.com).
</Note>

A virtual cluster is an isolated cluster created on a host cluster that your organization has already set up. To create a host cluster, refer to [Create a Cluster](/docs/continuum/create-a-cluster).

Your organization is billed for the host and [Cluster Virtualization add-on](/docs/continuum/editions-and-add-ons#add-ons); virtual clusters are not billed separately and only share the host's capacity based on usage. An idle virtual cluster consumes no compute. The virtual cluster's data remains on the host cluster and is preserved until the virtual cluster is explicitly deleted.

To learn more about virtual cluster concepts, read the [virtualization overview](/docs/continuum/virtualization-overview).

## Create a virtual cluster

In order to create a virtual cluster, you must have access to a Cockroach Continuum organization that has at least one [host cluster and workspace](/docs/continuum/workspaces).

A virtual cluster inherits the following configurations from the host and cannot be modified on their own:

* **Supported regions**: A virtual cluster can have a custom-set primary region bespoke for that cluster, but a virtual cluster cannot add regions not supported on the host.
* **Running CockroachDB version**: The CockroachDB version is inherited from the host; virtual clusters can run one <InternalLink version="releases" path="index">major version</InternalLink> behind the host cluster. Upgrades to a new version are performed on the host cluster and apply to all virtual clusters on that host.

You can create a virtual cluster in the Cloud Console, with the [ccloud CLI](/docs/cockroachcloud/ccloud-get-started), or with the [CockroachDB Cloud API](/docs/cockroachcloud/cloud-api).

### Cloud Console

To create a virtual cluster in the Cloud Console, follow these steps:

1. Log in to your Cockroach Continuum organization.
2. On the **Clusters** page, click **New cluster** and select a workspace under **Create in workspace**.
3. Review the listed details to confirm the workspace, select regions, and confirm the vCPU burst limit and CockroachDB version inherited from the host cluster.
4. Give your virtual cluster a name, and click **Create cluster**.

### ccloud CLI

To create a virtual cluster in the [ccloud CLI](/docs/cockroachcloud/ccloud-get-started), follow these steps:

1. Log into your organization with `ccloud auth`:
   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ccloud auth
   ```

2. Run `ccloud workspace list` to list available workspaces:
   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ccloud workspace list
   ```

3. Run `ccloud cluster create --workspace` with the workspace name and a cluster name to create a virtual cluster in that workspace:
   ```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
   ccloud cluster create --workspace {workspace-name} {cluster-name}
   ```

See the [Create a Virtual Cluster tutorial](/docs/continuum/tutorial-virtual-cluster) for more detailed instructions using the `ccloud` CLI.

### Cloud API

To create a virtual cluster, send a `POST` request to the `/v1/virtual-cluster-workspaces/{workspace_id}/clusters` endpoint, specifying the cluster name.

The service account associated with the secret key must have the Cluster Admin or Cluster Creator [role](/docs/cockroachcloud/authorization#organization-user-roles).

<CodeGroup>
  ```shell curl theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  curl --request POST \
    --url https://cockroachlabs.cloud/api/v1/virtual-cluster-workspaces/{workspace_id}/clusters \
    --header "Authorization: Bearer {secret_key}" \
    --json '{"name":"{cluster_name}"}'
  ```

  ```json Expanded JSON (Virtual cluster creation format) theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
  {
    "name": "{cluster_name}"
  }
  ```
</CodeGroup>

To list the workspaces available in an organization, send a `GET` request to the `/v1/virtual-cluster-workspaces` endpoint:

```shell theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
curl --request GET \
  --url https://cockroachlabs.cloud/api/v1/virtual-cluster-workspaces \
  --header "Authorization: Bearer {secret_key}"
```

## Connect to a virtual cluster

Each virtual cluster on a host has its own network security configuration, PostgreSQL connection string, and its own SQL users. Refer to the [Connect to a Cluster](/docs/cockroachcloud/connect-to-your-cluster) documentation for more information on network connectivity and security.

An application connecting to a virtual cluster cannot see or reach the host or any other virtual cluster in the workspace; no network configuration is necessary to ensure this level of isolation.

### PostgreSQL connection string

To generate the connection string for a virtual cluster, you can either navigate to the cluster in the Cloud Console and click the **Connect** button, or use the [ccloud CLI](/docs/cockroachcloud/ccloud-reference#get-connection-information-for-a-cluster).

On the first connection to a newly created cluster, you will be prompted to first create a SQL user. Learn more about SQL users in the [authorization documentation](/docs/stable/security-reference/authorization#sql-users).

### Model Context Protocol (MCP)

You can connect to a virtual cluster with the [CockroachDB MCP server](/docs/stable/cockroachdb-mcp-server). In the Cloud console, open the virtual cluster and click **Connect -> Model Context Protocol (MCP)** for specific instructions to set up different MCP clients to connect to the cluster.

## Scaling behavior

You do not size a virtual cluster. Virtual clusters scale with their workload, up to the maximum compute measured as a vCPU "burst limit". The default burst limit is set by the cluster's workspace at creation time of the virtual cluster. You can directly modify the burst limit of an individual virtual cluster, but this operation requires that you have the necessary permissions to modify the host cluster configuration as well.

An idle virtual cluster scales to zero and holds no compute. Its data remains durable on the host.

## Deletion

Delete a virtual cluster to remove it from the host cluster. Deletion has a 4-hour grace period: SQL connections are rejected immediately, but data is preserved and the deletion can be canceled. After the grace period the virtual cluster is removed, and its backups are retained for the shorter of the backup retention period or 30 days.

## Backup and restore

Backups are stored per virtual cluster. Each virtual cluster can have its own backup destination, and restores target one virtual cluster without affecting the host's other virtual clusters.

## Monitor a virtual cluster

The Cloud Console shows per-virtual-cluster metrics: CPU, queries per second, storage, and connections. Cockroach Continuum administrators can monitor individual virtual clusters as needed, but best practice is to monitor at the [host cluster and workspace](/docs/continuum/workspaces) level with observability tooling for ease of management.

Metrics can be [exported to Prometheus or Datadog](/docs/cockroachcloud/export-metrics).

## Feature availability on virtual clusters

Virtual clusters inherit the host's license entitlements, but not every cluster feature applies to a virtual cluster.

| Feature                                                                                                                    | On a virtual cluster                                                                                                                         |
| -------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| [Backups with revision history and PITR](/docs/stable/take-backups-with-revision-history-and-restore-from-a-point-in-time) | <span className="mark-yes">✓</span>                                                                                                          |
| Scheduled backups and restore                                                                                              | <span className="mark-yes">✓</span>                                                                                                          |
| [Encrypted backups](/docs/stable/take-and-restore-encrypted-backups)                                                       | <span className="mark-yes">✓</span>                                                                                                          |
| [Row-level security](/docs/stable/row-level-security)                                                                      | <span className="mark-yes">✓</span>                                                                                                          |
| [Column-level encryption](/docs/stable/column-level-encryption)                                                            | <span className="mark-yes">✓</span>                                                                                                          |
| [Changefeeds (CDC)](/docs/stable/change-data-capture-overview)                                                             | <span className="mark-yes">✓</span> (requires the host cluster to have the [Data Sync](/docs/continuum/editions-and-add-ons#add-ons) add-on) |
| Ingress private link                                                                                                       | <span className="mark-yes">✓</span>                                                                                                          |
| [Online restore](/docs/stable/restore)                                                                                     | ✗ (only on the [Mission Critical](/docs/continuum/editions-and-add-ons#editions) host itself)                                                |
| [CMEK](/docs/cockroachcloud/cmek)                                                                                          | ✗ (applies at the host cluster level and covers the host's virtual clusters through the host's key)                                          |
| [Physical cluster replication](/docs/stable/physical-cluster-replication-overview)                                         | ✗                                                                                                                                            |
| [Egress private link](/docs/cockroachcloud/egress-private-endpoints)                                                       | ✗                                                                                                                                            |
| [Egress perimeter control](/docs/cockroachcloud/egress-perimeter-controls)                                                 | ✗                                                                                                                                            |

The availability SLA for a virtual cluster is 99.99%, including on multi-region hosts.

## Known limitations

* A virtual cluster runs only within its host's regional footprint.
* Virtual clusters support up to approximately 10,000 schema objects per cluster.
* The CockroachDB version is inherited from the host and cannot be set per virtual cluster.
* Moving a virtual cluster to another host requires backup and restore with downtime.
* There is no separate RBAC model for virtual clusters. Existing cluster roles and permissions apply.