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

The following are required to start a PCR stream with CREATE VIRTUAL CLUSTER:

• The REPLICATIONDEST and MANAGEVIRTUALCLUSTER system privileges: The user starting the PCR stream from the standby cluster.
• The REPLICATIONSOURCE system privilege: The user specified in the connection string for the primary cluster.

Use the statement to grant the necessary privileges to users, for example:

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.
LIKE virtual\_cluster\_spec	Creates a virtual cluster with the same capabilities and settings as another 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.
replication\_options\_list	Options to modify the PCR streams. Refer to Options.

Options

Option	Description
READ VIRTUAL CLUSTER	() Create a on the standby cluster, which allows reads of the standby’s replicating virtual cluster. For an example, refer to Start a PCR stream with read from standby.

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. When you start a PCR stream, you can specify a virtual cluster 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.

Examples

Start a PCR stream

To start a PCR 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 PCR job. For details on the PCR stream, refer to the for SHOW VIRTUAL CLUSTER.

Start a PCR stream with read from standby

While physical cluster replication (PCR) is generally available, using the READ VIRTUAL CLUSTER option to read from a standby cluster is in .

Use the READ VIRTUAL CLUSTER option to set up a PCR stream that also creates a read-only virtual cluster on the standby cluster. You can create a PCR job as per the guide and then add the option to the CREATE VIRTUAL CLUSTER statement:

CREATE VIRTUAL CLUSTER main FROM REPLICATION OF main ON 'postgresql://{connection string to primary}' WITH READ VIRTUAL CLUSTER;

View the newly created virtual clusters:

SHOW VIRTUAL CLUSTERS;

You’ll find:

• The main virtual cluster, which is accepting writes from the primary cluster.
• The main-readonly virtual cluster, which is a read-only version of the main virtual cluster.

  id |     name      | data_state  | service_mode
-----+---------------+-------------+---------------
   1 | system        | ready       | shared
   3 | main          | replicating | none
   4 | main-readonly | ready       | shared
(3 rows)

To read table data from the standby cluster, connect to the readonly virtual cluster:

cockroach sql --url `"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=main-readonly&sslmode=verify-full"` --certs-dir=certs

You can only read data on the created readonly virtual cluster, other operations like SHOW VIRTUAL CLUSTERS must be run from the system virtual cluster. To connect to the readonly virtual cluster, refer to the .

If you started the PCR stream with the READ VIRTUAL CLUSTER option, failing over with SYSTEM TIME will destroy the readonly virtual cluster. If you fail over with LATEST, the readonly virtual cluster will remain on the original standby cluster, but will not update with new writes. Use to remove the readonly virtual cluster.

For details on adding a read-only virtual cluster after a failback, refer to the page.

See also