> ## Documentation Index
> Fetch the complete documentation index at: https://cockroachlabs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CREATE VIRTUAL CLUSTER

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

export const version = "v24.1";

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

The `CREATE VIRTUAL CLUSTER` statement creates a new virtual cluster. It is supported only starting a <InternalLink path="set-up-physical-cluster-replication">**physical cluster replication (PCR)** job</InternalLink>.

PCR happens between an *active* primary cluster and a *passive* standby cluster that accepts updates from the primary cluster. The unit of replication is a *virtual cluster*, which is part of the underlying infrastructure in the primary and standby clusters. The CockroachDB cluster has:

* The system virtual cluster manages the cluster's control plane and the replication of the cluster's data. Admins connect to the system virtual cluster to configure and manage the underlying CockroachDB cluster, set up PCR, create and manage a virtual cluster, and observe metrics and logs for the CockroachDB cluster and each virtual cluster.
* The application virtual cluster manages the cluster’s data plane. Application virtual clusters contain user data and run application workloads.

For more detail, refer to the <InternalLink path="physical-cluster-replication-overview">Physical Cluster Replication Overview</InternalLink>.

## Required privileges

`CREATE VIRTUAL CLUSTER` requires one of the following privileges:

* The `admin` role.
* The `MANAGEVIRTUALCLUSTER` <InternalLink path="security-reference/authorization#privileges">system privilege</InternalLink> allows the user to run all the related `VIRTUAL CLUSTER` SQL statements for PCR.

Use the <InternalLink path="grant">`GRANT SYSTEM`</InternalLink> statement:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
GRANT SYSTEM MANAGEVIRTUALCLUSTER TO user;
```

## Synopsis

xml version="1.0" encoding="UTF-8"?

<CreateVirtualCluster2 />

## Parameters

| Parameter                     | Description                                                                                                                |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `virtual\_cluster\_name`      | The name for the new virtual cluster.                                                                                      |
| `primary\_virtual\_cluster`   | The name of the primary's virtual cluster to replicate.                                                                    |
| `primary\_connection\_string` | The PostgreSQL connection string to the primary cluster. Refer to [Connection string](#connection-string) for more detail. |

## Connection string

When you <InternalLink path="set-up-physical-cluster-replication#step-4-start-replication">initiate a replication stream</InternalLink> from the standby cluster, it is necessary to pass a connection string to the system virtual cluster on the primary cluster:

```text theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
'postgresql://{replication user}:{password}@{node IP or hostname}:26257?options=-ccluster=system&sslmode=verify-full&sslrootcert=certs/{primary cert}.crt'
```

To form a connection string similar to the example, include the following values and query parameters. Replace values in <code>{'{...}'}</code> with the appropriate values for your configuration:

| Value                                  | Description                                                                                                                                                                                                                                                        |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| <code>{'{replication user}'}</code>    | The user on the primary cluster that has the `REPLICATION` system privilege. Refer to <InternalLink path="set-up-physical-cluster-replication#create-a-user-with-replication-privileges">Create a user with replication privileges</InternalLink> for more detail. |
| <code>{'{password}'}</code>            | The replication user's password.                                                                                                                                                                                                                                   |
| <code>{'{node ID or hostname}'}</code> | The node IP address or hostname of any node from the primary cluster.                                                                                                                                                                                              |
| `options=ccluster=system`              | The parameter to connect to the system virtual cluster on the primary cluster.                                                                                                                                                                                     |
| `sslmode=verify-full`                  | The `verify-full` secure connection type.                                                                                                                                                                                                                          |
| `sslrootcert={primary cert}`           | The path to the primary cluster's CA certificate on the standby cluster.                                                                                                                                                                                           |

## Capabilities

<Note>
  Cockroach Labs does not recommend changing the default capabilities of created virtual clusters.
</Note>

*Capabilities* control what a virtual cluster can do. The configuration profile included at startup creates the `template` virtual cluster with the same set of capabilities per CockroachDB version. When you start a replication stream, you can specify the `template` VC with `LIKE` to ensure other virtual clusters on the standby cluster will work in the same way. `LIKE` will refer to a virtual cluster on the CockroachDB cluster you're running the statement from.

## Example

### Start a replication stream

To start a replication stream to the standby of the primary's virtual cluster:

```sql theme={"theme":{"light":"catppuccin-mocha","dark":"catppuccin-mocha"}}
CREATE VIRTUAL CLUSTER main FROM REPLICATION OF main ON 'postgresql://{connection string to primary}';
```

This will create a `main` virtual cluster in the standby cluster. The standby's system virtual cluster will connect to the primary cluster to initiate the replication stream job. For detail on the replication stream, refer to the <InternalLink path="show-virtual-cluster#responses">Responses</InternalLink> for `SHOW VIRTUAL CLUSTER`.

## See also

* <InternalLink path="drop-virtual-cluster">`DROP VIRTUAL CLUSTER`</InternalLink>
* <InternalLink path="alter-virtual-cluster">`ALTER VIRTUAL CLUSTER`</InternalLink>
* <InternalLink path="show-virtual-cluster">`SHOW VIRTUAL CLUSTER`</InternalLink>