SHOW VIRTUAL CLUSTER

On this page Carat arrow pointing down
Note:

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

Note:

This is an enterprise-only feature. Request a 30-day trial license to try it out.

The SHOW VIRTUAL CLUSTER statement lists all virtual clusters running in a CockroachDB cluster. SHOW VIRTUAL CLUSTER supports inspecting virtual cluster status only as part of the physical cluster replication (PCR) workflow.

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

For more detail, refer to the Physical Cluster Replication Overview.

Required privileges

SHOW VIRTUAL CLUSTER requires either:

Use the GRANT SYSTEM statement:

icon/buttons/copy
GRANT SYSTEM MANAGEVIRTUALCLUSTER TO user;

Synopsis

SHOW VIRTUAL CLUSTERS CLUSTER virtual_cluster_spec WITH REPLICATION STATUS CAPABILITIES ,

Parameters

Parameter Description
virtual_cluster_spec The name of the virtual cluster.
REPLICATION STATUS Display the details of a replication stream.
CAPABILITIES Display the capabilities of a virtual cluster.

Responses

This table lists all possible responses from the different SHOW VIRTUAL CLUSTER statements:

Field Response
id The ID of a virtual cluster.
name The name of the standby (destination) virtual cluster.
data_state The state of the data on a virtual cluster. This can show one of the following: initializing replication, ready, replicating, replication paused, replication pending cutover, replication cutting over, replication error. Refer to Data state for more detail on each response.
service_mode The service mode shows whether a virtual cluster is ready to accept SQL requests. This can show none or shared. When shared, a virtual cluster's SQL connections will be served by the same nodes that are serving the system virtual cluster.
source_tenant_name The name of the primary (source) virtual cluster.
source_cluster_uri The URI of the primary (source) cluster. The standby cluster connects to the primary cluster using this URI when starting a replication stream.
replicated_time The latest timestamp at which the standby cluster has consistent data — that is, the latest time you can cut over to. This time advances automatically as long as the replication proceeds without error. replicated_time is updated periodically (every 30s).
retained_time The earliest timestamp at which the standby cluster has consistent data — that is, the earliest time you can cut over to.
replication_lag The time between the most up-to-date replicated time and the actual time. Refer to the Technical Overview for more detail.
cutover_time The time at which the cutover will begin. This can be in the past or the future. Refer to Cut over to a point in time.
status The status of the replication stream. This can show one of the following: initializing replication, ready, replicating, replication paused, replication pending cutover, replication cutting over, replication error. Refer to Data state for more detail on each response.
capability_name The capability name.
capability_value Whether the capability is enabled for a virtual cluster.
Tip:

To find the job ID for the replication stream, use the SHOW JOBS statement. For example:

icon/buttons/copy
SELECT * FROM [SHOW JOBS] WHERE job_type = 'REPLICATION STREAM INGESTION';

Data state

The data_state and status fields show the current state of a virtual cluster's data and progress of the replication stream job.

State Description
initializing replication The replication job is completing the initial scan of data from the primary cluster before it starts replicating data in real time.
ready A virtual cluster's data is ready for use.
replicating The replication job has started and is replicating data.
replication paused The replication job is paused due to an error or a manual request with ALTER VIRTUAL CLUSTER ... PAUSE REPLICATION.
replication pending cutover The replication job is running and the cutover time has been set. Once the the replication reaches the cutover time, the cutover will begin automatically.
replication cutting over The job has started cutting over. The cutover time can no longer be changed. Once cutover is complete, a virtual cluster will be available for use with ALTER VIRTUAL CLUSTER ... START SHARED SERVICE.
replication error An error has occurred. You can find more detail in the error message and the logs. Note: A PCR job will retry for 3 minutes before failing.

Examples

Show all virtual clusters

List all virtual clusters:

icon/buttons/copy
SHOW VIRTUAL CLUSTERS;

Show a virtual cluster

To show more details about the main virtual cluster:

icon/buttons/copy
SHOW VIRTUAL CLUSTER main;
icon/buttons/copy
  id | name | data_state  | service_mode
-----+------+-------------+---------------
   3 | main | replicating | none
(1 row)

Show replication status

To show the replication status of all virtual clusters:

icon/buttons/copy
SHOW VIRTUAL CLUSTERS WITH REPLICATION STATUS;

To show the replication status of the main virtual cluster:

icon/buttons/copy
SHOW VIRTUAL CLUSTER main WITH REPLICATION STATUS;
  id | name | source_tenant_name |              source_cluster_uri               |         retained_time         |    replicated_time     | replication_lag | cutover_time |   status
-----+------+--------------------+-----------------------------------------------+-------------------------------+------------------------+-----------------+--------------+--------------
   3 | main | main               | postgresql://user@hostname or IP:26257?redacted | 2024-04-18 10:07:45.000001+00 | 2024-04-18 14:07:45+00 | 00:00:19.602682 |         NULL | replicating
(1 row)

See also


Yes No
On this page

Yes No