diff --git a/src/current/_includes/v25.1/sidebar-data/cross-cluster-replication.json b/src/current/_includes/v25.1/sidebar-data/cross-cluster-replication.json index 925e3e2aca9..834556c1aa3 100644 --- a/src/current/_includes/v25.1/sidebar-data/cross-cluster-replication.json +++ b/src/current/_includes/v25.1/sidebar-data/cross-cluster-replication.json @@ -3,7 +3,7 @@ "is_top_level": true, "items": [ { - "title": "Logical Data Replication", + "title": "Logical Data Replication (LDR)", "items": [ { "title": "Overview", @@ -12,19 +12,19 @@ ] }, { - "title": "Set Up Logical Data Replication", + "title": "Set Up LDR", "urls": [ "/${VERSION}/set-up-logical-data-replication.html" ] }, { - "title": "Manage Logical Data Replication", + "title": "Manage LDR", "urls": [ "/${VERSION}/manage-logical-data-replication.html" ] }, { - "title": "Monitor Logical Data Replication", + "title": "Monitor LDR", "urls": [ "/${VERSION}/logical-data-replication-monitoring.html" ] @@ -32,7 +32,7 @@ ] }, { - "title": "Physical Cluster Replication", + "title": "Physical Cluster Replication (PCR)", "items": [ { "title": "Overview", @@ -41,7 +41,7 @@ ] }, { - "title": "Set Up Physical Cluster Replication", + "title": "Set Up PCR", "urls": [ "/${VERSION}/set-up-physical-cluster-replication.html" ] @@ -53,11 +53,17 @@ ] }, { - "title": "Monitor a Replication Stream", + "title": "Monitor PCR", "urls": [ "/${VERSION}/physical-cluster-replication-monitoring.html" ] }, + { + "title": "Manage PCR", + "urls": [ + "/${VERSION}/manage-physical-cluster-replication.html" + ] + }, { "title": "Technical Overview", "urls": [ diff --git a/src/current/v25.1/create-external-connection.md b/src/current/v25.1/create-external-connection.md index ba06ef057de..efec66c2627 100644 --- a/src/current/v25.1/create-external-connection.md +++ b/src/current/v25.1/create-external-connection.md @@ -66,7 +66,7 @@ Storage or sink | Operation support [HTTP(S)]({% link {{ page.version.version }}/changefeed-sinks.md %}) | Changefeeds [Kafka]({% link {{ page.version.version }}/changefeed-sinks.md %}#kafka) | Changefeeds [Nodelocal]({% link {{ page.version.version }}/use-cloud-storage.md %}) | Backups, restores, imports, exports, changefeeds -[PostgreSQL]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#connection-reference) connections | Physical cluster replication +[PostgreSQL]({% link {{ page.version.version }}/manage-physical-cluster-replication.md %}#connection-reference) connections | Physical cluster replication [Userfile]({% link {{ page.version.version }}/use-userfile-storage.md %}) | Backups, restores, imports, exports, changefeeds [Webhook]({% link {{ page.version.version }}/changefeed-sinks.md %}#webhook-sink) | Changefeeds diff --git a/src/current/v25.1/create-virtual-cluster.md b/src/current/v25.1/create-virtual-cluster.md index 76c96b93dc3..c02e7c2e8e8 100644 --- a/src/current/v25.1/create-virtual-cluster.md +++ b/src/current/v25.1/create-virtual-cluster.md @@ -150,7 +150,7 @@ cockroach sql --url `"postgresql://root@{node IP or hostname}:{26257}?options=-c ~~~ {{site.data.alerts.callout_info}} -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 [Connection Reference]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#connection-reference). +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 [Connection Reference]({% link {{ page.version.version }}/manage-physical-cluster-replication.md %}#connection-reference). {{site.data.alerts.end}} {% include {{ page.version.version }}/physical-replication/failover-read-virtual-cluster.md %} Use [`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) to remove the `readonly` virtual cluster. diff --git a/src/current/v25.1/failover-replication.md b/src/current/v25.1/failover-replication.md index 75788baf1c1..3be68262596 100644 --- a/src/current/v25.1/failover-replication.md +++ b/src/current/v25.1/failover-replication.md @@ -223,7 +223,7 @@ This section illustrates the steps to fail back to the original primary cluster ~~~ {{site.data.alerts.callout_success}} - For details on connection strings, refer to the [Connection reference]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#connection-reference). + For details on connection strings, refer to the [Connection reference]({% link {{ page.version.version }}/manage-physical-cluster-replication.md %}#connection-reference). {{site.data.alerts.end}} 1. Connect to the system virtual cluster for **Cluster B**: diff --git a/src/current/v25.1/manage-physical-cluster-replication.md b/src/current/v25.1/manage-physical-cluster-replication.md new file mode 100644 index 00000000000..dc371fe8a97 --- /dev/null +++ b/src/current/v25.1/manage-physical-cluster-replication.md @@ -0,0 +1,95 @@ +--- +title: Manage Physical Cluster Replication +summary: Learn how to manage a physical cluster replication (PCR) stream. +toc: true +--- + +[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. +This page describes: + +- [Connecting to and interacting with](#connection-reference) the system virtual cluser and virtual clusters on each physical cluster. +- [Managing PCR](#manage-replication-in-the-sql-shell) using SQL statements. +- [Upgrading CockroachDB](#upgrade-the-cluster-version-on-the-primary-and-standby) on both the primary and standby clusters. + +## Connection reference + +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 %}). + +{{site.data.alerts.callout_success}} +You can use an [external connection]({% link {{ page.version.version }}/create-external-connection.md %}) to define a name for connections using the `postgresql://` scheme. +{{site.data.alerts.end}} + +The table uses `main` as an example name for the virtual cluster that contains user table data in the primary and standby clusters. + +Cluster | Virtual Cluster | Usage | URL and Parameters +--------+-----------------+-------+------------------- +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"`

Use the `--certs-dir` flag to specify the path to your certificate. +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"`

{% include {{ page.version.version }}/connect/cockroach-workload-parameters.md %} As a result, for the example in this tutorial, you will need:

+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"`

Use the `--certs-dir` flag to specify the path to your certificate. +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"`

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:

+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"`

Use the `--certs-dir` flag to specify the path to your certificate. + +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). + +## Manage replication in the SQL shell + +To start, manage, and observe PCR, you can use the following SQL statements: + +Statement | Action +----------+------ +[`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). +[`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. +[`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters and PCR stream status in the physical cluster. +[`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster. + +## Upgrade the cluster version on the primary and standby + +{{site.data.alerts.callout_danger}} +The standby cluster must be at the same version as, or one version ahead of, the primary's virtual cluster. +{{site.data.alerts.end}} + +To upgrade the primary and standby clusters in PCR, complete the following steps in order: + +### Step 1. Upgrade the binary on both clusters + +Upgrade the binary on **every node** in both the primary and standby clusters: + +1. Replace the `cockroach` binary on each node. +1. Restart CockroachDB each node. + +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). + +### Step 2. Finalize the upgrade on each virtual cluster + +You must finalize the upgrade on each virtual cluster in this order: + +1. Standby system virtual cluster +1. Primary system virtual cluster +1. Standby application virtual cluster +1. Primary application virtual cluster + +Repeat these steps for **each** virtual cluster in the specified order. To finalize a virtual cluster: + +1. Connect to the virtual cluster using the SQL shell: + + {% include_cached copy-clipboard.html %} + ~~~ shell + cockroach sql "" + ~~~ + + Use the [Connection reference](#connection-reference) to find the correct connection strings. + +1. Run the following command, replacing `{VERSION}` with the target major version (e.g., `{{ page.version.version }}`): + + {% include_cached copy-clipboard.html %} + ~~~ sql + SET CLUSTER SETTING version = '{VERSION}'; + ~~~ + +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. + +{{site.data.alerts.callout_info}} +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. +{{site.data.alerts.end}} + +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. \ No newline at end of file diff --git a/src/current/v25.1/physical-cluster-replication-overview.md b/src/current/v25.1/physical-cluster-replication-overview.md index ca45d2debfb..f3ead45c794 100644 --- a/src/current/v25.1/physical-cluster-replication-overview.md +++ b/src/current/v25.1/physical-cluster-replication-overview.md @@ -50,42 +50,13 @@ Frequent large schema changes or imports may cause a significant spike in [repli ## Get started -This section is a quick overview of the initial requirements to start a replication stream. For more comprehensive guides, refer to: +To get started with PCR, refer to the following pages: - [Set Up Physical Cluster Replication]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}): for a tutorial on how to start a replication stream. - [Physical Cluster Replication Monitoring]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}): for detail on metrics and observability into a replication stream. - [Fail Over from a Primary Cluster to a Standby Cluster]({% link {{ page.version.version }}/failover-replication.md %}): for a guide on how to complete a replication stream and fail over to the standby cluster. - [Technical Overview]({% link {{ page.version.version }}/physical-cluster-replication-technical-overview.md %}): to understand PCR in more depth before setup. -### Manage replication in the SQL shell - -To start, manage, and observe PCR, you can use the following SQL statements: - -Statement | Action -----------+------ -[`CREATE VIRTUAL CLUSTER ... FROM REPLICATION OF ...`]({% link {{ page.version.version }}/create-virtual-cluster.md %}) | Start a replication stream. -[`ALTER VIRTUAL CLUSTER ... PAUSE REPLICATION`]({% link {{ page.version.version }}/alter-virtual-cluster.md %}) | Pause a running replication stream. -[`ALTER VIRTUAL CLUSTER ... RESUME REPLICATION`]({% link {{ page.version.version }}/alter-virtual-cluster.md %}) | Resume a paused replication stream. -[`ALTER VIRTUAL CLUSTER ... START SERVICE SHARED`]({% link {{ page.version.version }}/alter-virtual-cluster.md %}#start-a-virtual-cluster) | Initiate a [failover]({% link {{ page.version.version }}/failover-replication.md %}). -[`SHOW VIRTUAL CLUSTER`]({% link {{ page.version.version }}/show-virtual-cluster.md %}) | Show all virtual clusters. -[`DROP VIRTUAL CLUSTER`]({% link {{ page.version.version }}/drop-virtual-cluster.md %}) | Remove a virtual cluster. - -## Cluster versions and upgrades - -{{site.data.alerts.callout_danger}} -The standby cluster must be at the same version as, or one version ahead of, the primary's virtual cluster. -{{site.data.alerts.end}} - -When PCR is enabled, upgrade with the following procedure. 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: - -1. [Upgrade the binaries]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#perform-a-major-version-upgrade) on the primary and standby clusters. Replace the binary on each node of the cluster and restart the node. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's system virtual cluster if auto-finalization is disabled. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's system virtual cluster if auto-finalization is disabled. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the standby's virtual cluster. -1. [Finalize]({% link {{ page.version.version }}/upgrade-cockroach-version.md %}#finalize-a-major-version-upgrade-manually) the upgrade on the primary's virtual cluster. - -The standby cluster must be at the same version as, or one version ahead of, the primary's virtual cluster at the time of [failover]({% link {{ page.version.version }}/failover-replication.md %}). - ## Demo video Learn how to use PCR to meet your RTO and RPO requirements with the following demo: diff --git a/src/current/v25.1/set-up-physical-cluster-replication.md b/src/current/v25.1/set-up-physical-cluster-replication.md index 060d9be751d..af06e5c2da4 100644 --- a/src/current/v25.1/set-up-physical-cluster-replication.md +++ b/src/current/v25.1/set-up-physical-cluster-replication.md @@ -264,7 +264,7 @@ To create certificates signed by an external certificate authority, refer to [Cr At this point, the primary and standby clusters are both running. The next step allows the standby cluster to connect to the primary cluster and begin ingesting its data. Depending on how you manage certificates, you must ensure that all nodes on the primary and the standby cluster have access to the certificate of the other cluster. -You can use the `cockroach encode-uri` command to generate a connection string containing a cluster's certificate for any [PCR statements]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}#manage-replication-in-the-sql-shell) that require a connection string. +You can use the `cockroach encode-uri` command to generate a connection string containing a cluster's certificate for any [PCR statements]({% link {{ page.version.version }}/manage-physical-cluster-replication.md %}#manage-replication-in-the-sql-shell) that require a connection string. For example, in this tutorial you will need a connection string for the primary cluster when you start the replication stream from the standby. @@ -458,26 +458,6 @@ To _fail over_ to the standby cluster, follow the instructions on the [Fail Over For details on how to _fail back_ after replicating a non-virtualized cluster, refer to [Fail back after PCR from an existing cluster]({% link {{ page.version.version }}/failover-replication.md %}#fail-back-after-pcr-from-an-existing-cluster). -## Connection reference - -This table outlines the connection strings you will need for this setup tutorial. - -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). - -{{site.data.alerts.callout_success}} -You can use an [external connection]({% link {{ page.version.version }}/create-external-connection.md %}) to define a name for connections using the `postgresql://` scheme. -{{site.data.alerts.end}} - -The table uses `main` as an example name for the virtual cluster that contains user table data in the primary and standby clusters. - -Cluster | Virtual Cluster | Usage | URL and Parameters ---------+-----------------+-------+------------------- -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"`Use the `--certs-dir` flag to specify the path to your certificate. -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"`

{% include {{ page.version.version }}/connect/cockroach-workload-parameters.md %} As a result, for the example in this tutorial, you will need: -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"`Use the `--certs-dir` flag to specify the path to your certificate. -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"`

Generate the connection string with [`cockroach encode-uri`](#step-3-manage-the-cluster-certificates). Use the generated connection string in: -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"`Use the `--certs-dir` flag to specify the path to your certificate. - ## What's next - [Physical Cluster Replication Monitoring]({% link {{ page.version.version }}/physical-cluster-replication-monitoring.md %}) diff --git a/src/current/v25.1/show-external-connection.md b/src/current/v25.1/show-external-connection.md index 68730b1db29..24cc02de004 100644 --- a/src/current/v25.1/show-external-connection.md +++ b/src/current/v25.1/show-external-connection.md @@ -34,7 +34,7 @@ Response | Description ---------+------------ `connection_name` | The user-specified name of the external connection. `connection_uri` | The [storage/sink]({% link {{ page.version.version }}/create-external-connection.md %}#supported-external-storage-and-sinks) URI that the external connection references. -`connection_type` | Possible values are:
. +`connection_type` | Possible values are:
. ## Examples