Virtual Clusters

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

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. Your organization is billed for the host and Cluster Virtualization add-on; 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.

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. 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 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, or with the CockroachDB Cloud API.

Cloud Console

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

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

ccloud CLI

To create a virtual cluster in the ccloud CLI, follow these steps:

Log into your organization with ccloud auth:
ccloud auth
Run ccloud workspace list to list available workspaces:
ccloud workspace list
Run ccloud cluster create --workspace with the workspace name and a cluster name to create a virtual cluster in that workspace:
ccloud cluster create --workspace {workspace-name} {cluster-name}

See the Create a Virtual Cluster tutorial 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.

curl --request POST \
  --url https://cockroachlabs.cloud/api/v1/virtual-cluster-workspaces/{workspace_id}/clusters \
  --header "Authorization: Bearer {secret_key}" \
  --json '{"name":"{cluster_name}"}'

{
  "name": "{cluster_name}"
}

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

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

Model Context Protocol (MCP)

You can connect to a virtual cluster with the 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 level with observability tooling for ease of management. Metrics can be exported to Prometheus or Datadog.

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	✓
Scheduled backups and restore	✓
Encrypted backups	✓
Row-level security	✓
Column-level encryption	✓
Changefeeds (CDC)	✓ (requires the host cluster to have the Data Sync add-on)
Ingress private link	✓
Online restore	✗ (only on the Mission Critical host itself)
CMEK	✗ (applies at the host cluster level and covers the host’s virtual clusters through the host’s key)
Physical cluster replication	✗
Egress private link	✗
Egress perimeter control	✗

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.

Onboard Data and Build Applications

Scale Production Workloads

Monitor and Optimize Performance

Integrate and Govern Your Ecosystem

Create a virtual cluster

Cloud Console

ccloud CLI

Cloud API

Connect to a virtual cluster

PostgreSQL connection string

Model Context Protocol (MCP)

Scaling behavior

Deletion

Backup and restore

Monitor a virtual cluster

Feature availability on virtual clusters

Known limitations

​Create a virtual cluster

​Cloud Console

​ccloud CLI

​Cloud API

​Connect to a virtual cluster

​PostgreSQL connection string

​Model Context Protocol (MCP)

​Scaling behavior

​Deletion

​Backup and restore

​Monitor a virtual cluster

​Feature availability on virtual clusters

​Known limitations

Create a virtual cluster

Cloud Console

ccloud CLI

Cloud API

Connect to a virtual cluster

PostgreSQL connection string

Model Context Protocol (MCP)

Scaling behavior

Deletion

Backup and restore

Monitor a virtual cluster

Feature availability on virtual clusters

Known limitations