|
| 1 | +--- |
| 2 | +title: Manage Physical Cluster Replication |
| 3 | +summary: Learn how to manage a physical cluster replication (PCR) stream. |
| 4 | +toc: true |
| 5 | +--- |
| 6 | + |
| 7 | +[Physical cluster replication (PCR)]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}) enables continuous replication of data from an active primary cluster to a passive standby cluster, supporting high availability and disaster recovery scenarios. |
| 8 | +This page describes: |
| 9 | + |
| 10 | +- [Connecting to and interacting with](#connection-reference) the system virtual cluser and virtual clusters on each physical cluster. |
| 11 | +- [Managing PCR](#manage-replication-in-the-sql-shell) using SQL statements. |
| 12 | +- [Upgrading CockroachDB](#upgrade-the-cluster-version-on-the-primary-and-standby) on both the primary and standby clusters. |
| 13 | + |
| 14 | +## Connection reference |
| 15 | + |
| 16 | +This table outlines the connection strings to connect to the primary and standby cluster's [virtual clusters]({% link {{ page.version.version }}/cluster-virtualization-overview.md %}). |
| 17 | + |
| 18 | +{{site.data.alerts.callout_success}} |
| 19 | +You can use an [external connection]({% link {{ page.version.version }}/create-external-connection.md %}) to define a name for connections using the `postgresql://` scheme. |
| 20 | +{{site.data.alerts.end}} |
| 21 | + |
| 22 | +The table uses `main` as an example name for the virtual cluster that contains user table data in the primary and standby clusters. |
| 23 | + |
| 24 | +Cluster | Virtual Cluster | Usage | URL and Parameters |
| 25 | +--------+-----------------+-------+------------------- |
| 26 | +Primary | System | Set up a replication user and view running virtual clusters. Connect with [`cockroach sql`]({% link {{ page.version.version }}/cockroach-sql.md %}). | `"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=system&sslmode=verify-full"`<br><br><ul><li>`options=-ccluster=system`</li><li>`sslmode=verify-full`</li></ul>Use the `--certs-dir` flag to specify the path to your certificate. |
| 27 | +Primary | Main | Add and run a workload with [`cockroach workload`]({% link {{ page.version.version }}/cockroach-workload.md %}). | `"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=main&sslmode=verify-full&sslrootcert=certs/ca.crt&sslcert=certs/client.root.crt&sslkey=certs/client.root.key"`<br><br>{% include {{ page.version.version }}/connect/cockroach-workload-parameters.md %} As a result, for the example in this tutorial, you will need:<br><br><ul><li>`options=-ccluster={virtual_cluster_name}`</li><li>`sslmode=verify-full`</li><li>`sslrootcert={path}/certs/ca.crt`</li><li>`sslcert={path}/certs/client.root.crt`</li><li>`sslkey={path}/certs/client.root.key`</li></ul> |
| 28 | +Standby | System | Manage the replication stream. Connect with [`cockroach sql`]({% link {{ page.version.version }}/cockroach-sql.md %}). | `"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=system&sslmode=verify-full"`<br><br><ul><li>`options=-ccluster=system`</li><li>`sslmode=verify-full`</li></ul>Use the `--certs-dir` flag to specify the path to your certificate. |
| 29 | +Standby/Primary | System | Connect to the other cluster. | `"postgresql://{replication user}:{password}@{node IP or hostname}:{26257}/defaultdb?options=-ccluster%3Dsystem&sslinline=true&sslmode=verify-full&sslrootcert=-----BEGIN+CERTIFICATE-----{encoded_cert}-----END+CERTIFICATE-----%0A"`<br><br>Generate the connection string with [`cockroach encode-uri`]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-3-manage-the-cluster-certificates). Use the generated connection string in:<br><br><ul><li>`CREATE VIRTUAL CLUSTER` statements to [start the replication stream]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-4-start-replication).</li><li>`ALTER VIRTUAL CLUSTER` statements to [fail back to the primary cluster]({% link {{ page.version.version }}/failover-replication.md %}#failback).</li></ul> |
| 30 | +Standby | Read only | Run read queries on the standby's replicating virtual cluster | `"postgresql://root@{node IP or hostname}:{26257}?options=-ccluster=main-readonly&sslmode=verify-full"`<br><br><ul><li>`options=-ccluster=main-readonly`</li><li>`sslmode=verify-full`</li></ul>Use the `--certs-dir` flag to specify the path to your certificate. |
| 31 | + |
| 32 | +For additional detail on the standard CockroachDB connection parameters, refer to [Client Connection Parameters]({% link {{ page.version.version }}/connection-parameters.md %}#connect-using-a-url). |
| 33 | + |
| 34 | +## Manage replication in the SQL shell |
| 35 | + |
| 36 | +To start, manage, and observe PCR, you can use the following SQL statements: |
| 37 | + |
| 38 | +Statement | Action |
| 39 | +----------+------ |
| 40 | +[`CREATE VIRTUAL CLUSTER ... FROM REPLICATION OF ...`]({% link {{ page.version.version }}/create-virtual-cluster.md %}) | Start a PCR stream and [configure the stream's behavior]({% link {{ page.version.version }}/create-virtual-cluster.md %}#options). |
| 41 | +[`ALTER VIRTUAL CLUSTER`]({% link {{ page.version.version }}/alter-virtual-cluster.md %}) | Pause and resume PCR streams, [initiate a failover]({% link {{ page.version.version }}/alter-virtual-cluster.md %}#start-the-failover-process), and configure a running stream's behavior. |
| 42 | +[`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters and PCR stream status in the physical cluster. |
| 43 | +[`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster. |
| 44 | + |
| 45 | +## Upgrade the cluster version on the primary and standby |
| 46 | + |
| 47 | +{{site.data.alerts.callout_danger}} |
| 48 | +The standby cluster must be at the same version as, or one version ahead of, the primary's virtual cluster. |
| 49 | +{{site.data.alerts.end}} |
| 50 | + |
| 51 | +To upgrade the primary and standby clusters in PCR, complete the following steps in order: |
| 52 | + |
| 53 | +### Step 1. Upgrade the binary on both clusters |
| 54 | + |
| 55 | +Upgrade the binary on **every node** in both the primary and standby clusters: |
| 56 | + |
| 57 | +1. Replace the `cockroach` binary on each node. |
| 58 | +1. Restart CockroachDB each node. |
| 59 | + |
| 60 | +You can find more details on upgrading the binary in [Perform a major-version upgrade]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade). |
| 61 | + |
| 62 | +### Step 2. Finalize the upgrade on each virtual cluster |
| 63 | + |
| 64 | +You must finalize the upgrade on each virtual cluster in this order: |
| 65 | + |
| 66 | +1. Standby system virtual cluster |
| 67 | +1. Primary system virtual cluster |
| 68 | +1. Standby application virtual cluster |
| 69 | +1. Primary application virtual cluster |
| 70 | + |
| 71 | +Repeat these steps for **each** virtual cluster in the specified order. To finalize a virtual cluster: |
| 72 | + |
| 73 | +1. Connect to the virtual cluster using the SQL shell: |
| 74 | + |
| 75 | + {% include_cached copy-clipboard.html %} |
| 76 | + ~~~ shell |
| 77 | + cockroach sql "<connection string>" |
| 78 | + ~~~ |
| 79 | + |
| 80 | + Use the [Connection reference](#connection-reference) to find the correct connection strings. |
| 81 | + |
| 82 | +1. Run the following command, replacing `{VERSION}` with the target major version (e.g., `{{ page.version.version }}`): |
| 83 | + |
| 84 | + {% include_cached copy-clipboard.html %} |
| 85 | + ~~~ sql |
| 86 | + SET CLUSTER SETTING version = '{VERSION}'; |
| 87 | + ~~~ |
| 88 | + |
| 89 | +This upgrades the standby cluster before the primary cluster. Within the primary and standby CockroachDB clusters, the system virtual cluster must be at a cluster version greater than or equal to the virtual cluster. |
| 90 | + |
| 91 | +{{site.data.alerts.callout_info}} |
| 92 | +It is possible to perform a failover from the primary to the standby during the upgrade; however, you will not be able perform a failback from the promoted original standby when it is a version ahead of the original primary cluster. |
| 93 | +{{site.data.alerts.end}} |
| 94 | + |
| 95 | +For more details on finalizing or rolling back the upgrade, refer to [Upgrade CockroachDB self-hosted]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}) page. |
0 commit comments