This feature is in preview. This feature is subject to change. To share feedback and/or issues, contact Support.
This is an enterprise-only feature. You can use free trial credits to try it out.
New in v23.2:
The CREATE VIRTUAL CLUSTER statement creates a new virtual cluster. It is supported only starting a physical cluster replication (PCR) job.
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.
- Each other virtual cluster manages its own data plane. Users connect to a virtual cluster by default, rather than the system virtual cluster. To connect to the system virtual cluster, the connection string must be modified. Virtual clusters contain user data and run application workloads. When PCR is enabled, the non-system virtual cluster on both primary and secondary clusters is named
application.
For more detail, refer to the Physical Cluster Replication Overview.
Required privileges
CREATE VIRTUAL CLUSTER requires one of the following privileges:
- The
adminrole. - The
MANAGEVIRTUALCLUSTERsystem privilege allows the user to run all the relatedVIRTUAL CLUSTERSQL statements for PCR.
Use the GRANT SYSTEM statement:
GRANT SYSTEM MANAGEVIRTUALCLUSTER TO user;
Synopsis
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 replication streams. Refer to Options. |
Options
| Option | Description |
|---|---|
RETENTION |
Configure a retention window that will control how far in the past you can cut over to. We do not recommend setting RETENTION much higher than the 24-hour default on the standby cluster. Accumulated data from an excessive retention (cutover) window could affect queries running on the standby cluster that is active following a cutover. |
Connection string
When you initiate a replication stream 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 |
|---|---|
{replication user} |
The user on the primary cluster that has the REPLICATION system privilege. Refer to the Create a replication user and password for more detail. |
{password} |
The replication user's password. |
{node ID or hostname} |
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.
Examples
Start a replication stream
To start a replication stream to the standby of the primary's application virtual cluster:
CREATE VIRTUAL CLUSTER application LIKE template FROM REPLICATION OF application ON 'postgresql://{connection string to primary}';
This will create a virtual cluster in the standby cluster that is based on the template virtual cluster, which is created during cluster startup with --config-profile. 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 Responses for SHOW VIRTUAL CLUSTER.
Specify a retention window for a replication stream
When you initiate a replication stream, you can specify a retention window to protect data from garbage collection. The retention window controls how far in the past you can cut over to:
CREATE VIRTUAL CLUSTER application LIKE template FROM REPLICATION OF application ON 'postgresql://{connection string to primary}' WITH RETENTION '36h';
This will initiate a replication stream from the primary cluster into the standby cluster's new standbyapplication virtual cluster. The RETENTION option allows you to specify a timestamp in the past for cutover to the standby cluster. After cutover, the standbyapplication will be transactionally consistent to any timestamp within that retention window.
We do not recommend setting RETENTION much higher than the 24-hour default on the standby cluster. Accumulated data from an excessive retention (cutover) window could affect queries running on the standby cluster that is active following a cutover.
See also
Was this helpful?
