CREATE VIRTUAL CLUSTER

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

The CREATE VIRTUAL CLUSTER statement creates a new virtual cluster. It is supported only starting a .

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 .

Required privileges

CREATE VIRTUAL CLUSTER requires one of the following privileges:

• The admin role.
• The MANAGEVIRTUALCLUSTER allows the user to run all the related VIRTUAL CLUSTER SQL statements for PCR.

Use the statement:

GRANT SYSTEM MANAGEVIRTUALCLUSTER TO user;

Synopsis

xml version=“1.0” encoding=“UTF-8”?

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 for more detail.

Connection string

When you from the standby cluster, it is necessary to pass a connection string to the system virtual cluster on the primary cluster:

'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 with the appropriate values for your configuration:

Value	Description
The user on the primary cluster that has the REPLICATION system privilege. Refer to for more detail.
The replication user’s password.
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

Cockroach Labs does not recommend changing the default capabilities of created virtual clusters.

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:

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 for SHOW VIRTUAL CLUSTER.

See also