Docs for PCR on Cloud cluster #19503
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
katmayb
changed the title
Files changed:
|
✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.
|
✅ Deploy Preview for cockroachdb-api-docs canceled.
|
✅ Netlify Preview
To edit notification comments on pull requests, go to your Netlify project configuration. |
katmayb
changed the title
alicia-l2
reviewed
Jun 23, 2025
alicia-l2
reviewed
Jun 23, 2025
alicia-l2
approved these changes
Jun 25, 2025
| - Physical cluster replication is supported in CockroachDB {{ site.data.products.core }} clusters on v23.2 or later. The primary cluster can be a [new]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-1-create-the-primary-cluster) or [existing]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#set-up-pcr-from-an-existing-cluster) cluster. The standby cluster must be a [new cluster started with the `--virtualized-empty` flag]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-2-create-the-standby-cluster). | ||
| - Physical cluster replication is supported in: | ||
| - CockroachDB {{ site.data.products.core }} clusters on v23.2 or later. The primary cluster can be a [new]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-1-create-the-primary-cluster) or [existing]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#set-up-pcr-from-an-existing-cluster) cluster. The standby cluster must be a [new cluster started with the --virtualized-empty flag]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-2-create-the-standby-cluster). | ||
| - [CockroachDB {{ site.data.products.advanced }} in clusters]({% link cockroachcloud/physical-cluster-replication.md %}) on v25.2 or later. |
There was a problem hiding this comment.
We support it in clusters 24.3 or later
|
|
||
| CockroachDB **physical cluster replication (PCR)** continuously sends all data at the cluster level from a _primary_ cluster to an independent _standby_ cluster. Existing data and ongoing changes on the active primary cluster, which is serving application data, replicate asynchronously to the passive standby cluster. | ||
|
|
||
| PCR provides a **two-datacenter resiliency strategy** where clusters are limited to two regions. In a disaster recovery scenario, you can [fail over](#fail-over-to-the-standby-cluster) from the unavailable primary cluster to the standby cluster. This will stop the PCR stream, reset the standby cluster to a point in time where all ingested data is consistent, and mark the standby as ready to accept application traffic. |
There was a problem hiding this comment.
can we say 'to the available standby cluster'
|
|
||
| You'll need the following: | ||
|
|
||
| - **Two CockroachDB {{ site.data.products.advanced }} clusters.** To set up PCR successfully, configure your clusters as per the following: |
There was a problem hiding this comment.
can we add a big note here that says 'you must have the pcr flag enabled when you create the cluster'
| } | ||
| ~~~ | ||
|
|
||
| - `failover_at`: The requested timestamp for failover. If you used `"status":"FAILING_OVER"` to initiate the failover and omitted `failover_at`, the failover time will default to the latest consistent replicated time. |
There was a problem hiding this comment.
instead of 'if you used' can we phrase it like 'you can use'
|
|
||
| ### Fail back to the primary cluster | ||
|
|
||
| To fail back from the standby to the primary cluster, start another PCR stream with the standby cluster as the `primary_cluster_id` and the original primary cluster as the `standby_cluster_id`. You can only fail back to the original primary cluster if the cluster was created with the `"support_physical_cluster_replication"` set to `true`. |
There was a problem hiding this comment.
can we remove the final sentence on the 'support pcr' set to true
davidwding
approved these changes
Jun 26, 2025
rmloveland
approved these changes
Jun 26, 2025
| @@ -1,3 +1,6 @@ | |||
| - Physical cluster replication is supported in CockroachDB {{ site.data.products.core }} clusters on v23.2 or later. The primary cluster can be a [new]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-1-create-the-primary-cluster) or [existing]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#set-up-pcr-from-an-existing-cluster) cluster. The standby cluster must be a [new cluster started with the `--virtualized-empty` flag]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-2-create-the-standby-cluster). | |||
| - Physical cluster replication is supported in: | |||
There was a problem hiding this comment.
suggest code formatting for the --virtualized-empty flag unless maybe it broke something?
| - Physical cluster replication is supported in: | ||
| - CockroachDB {{ site.data.products.core }} clusters on v23.2 or later. The primary cluster can be a [new]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-1-create-the-primary-cluster) or [existing]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#set-up-pcr-from-an-existing-cluster) cluster. The standby cluster must be a [new cluster started with the --virtualized-empty flag]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#step-2-create-the-standby-cluster). | ||
| - [CockroachDB {{ site.data.products.advanced }} in clusters]({% link cockroachcloud/physical-cluster-replication.md %}) on v24.3 or later. | ||
| - The primary and standby clusters must have the same [zone configurations]({% link {{ page.version.version }}/configure-replication-zones.md %}) in CockroachDB self-hosted. |
There was a problem hiding this comment.
i think "CockroachDB self-hosted" can be expressed as
CockroachDB {{ site.data.products.core }}
sorry to annoy, i spent a lot of time searching for these free-form usages a while ago :-D
|
|
||
| CockroachDB **physical cluster replication (PCR)** continuously sends all data at the cluster level from a _primary_ cluster to an independent _standby_ cluster. Existing data and ongoing changes on the active primary cluster, which is serving application data, replicate asynchronously to the passive standby cluster. | ||
|
|
||
| PCR provides a **two-datacenter resiliency strategy** where clusters are limited to two regions. In a disaster recovery scenario, you can [fail over](#fail-over-to-the-standby-cluster) from the unavailable primary cluster to the available standby cluster. This will stop the PCR stream, reset the standby cluster to a point in time where all ingested data is consistent, and mark the standby as ready to accept application traffic. |
There was a problem hiding this comment.
this could be followed by (2DC) in parens or something since I have also seen it referred to as that
| In this guide, you'll use the [{{ site.data.products.cloud }} API]({% link cockroachcloud/cloud-api.md %}) to set up PCR from a primary cluster to a standby cluster, monitor the PCR stream, and fail over from the primary to the standby cluster. | ||
|
|
||
| {{site.data.alerts.callout_info}} | ||
| PCR is supported on CockroachDB {{ site.data.products.advanced }} and CockroachDB self-hosted clusters. For a guide to setting up PCR on CockroachDB self-hosted, refer to the [Set Up Physical Cluster Replication]({% link {{ site.current_cloud_version }}/set-up-physical-cluster-replication.md %}) tutorial. |
There was a problem hiding this comment.
as mentioned above i think "self-hosted" can be expressed as {{ site.data.products.core }}
| - Clusters must be in the same cloud (AWS, GCP, or Azure). | ||
| - Clusters must be single [region]({% link cockroachcloud/regions.md %}) (multiple availability zones per cluster is supported). | ||
| - The primary and standby cluster in AWS and Azure must be in different regions. | ||
| - The primary and standby cluster in GCP can be in the same region, but must not have overlapping CIDR ranges. |
There was a problem hiding this comment.
is there a CIDR range setup thing we can link to?
| - `"primary_cluster_id"`, `"standby_cluster_id"`: The cluster IDs of the primary and standby clusters. | ||
| - `"created_at"`: The time at which the PCR stream was created. | ||
|
|
||
| To start PCR between clusters, CockroachDB {{ site.data.products.cloud }} sets up VPC peering between clusters and validates the connectivity. As a result, it may take around 5 minutes to initialize the PCR job during which the status will be `STARTING`. |
There was a problem hiding this comment.
do we have cloud docs on setting up VPC peering to link to?
| Replace: | ||
|
|
||
| - `api_secret_key` with your API secret key. | ||
| - `job_id` with the PCR job's ID. You can find this in the response from when you created the PCR stream. |
There was a problem hiding this comment.
same as above re: "job" linking to some kind of job docs?
| - `"id"`: The ID of the PCR stream. | ||
| - `"status"`: The status of the PCR stream. For descriptions, refer to [Status](#status). | ||
| - `"primary_cluster_id"`, `"standby_cluster_id"`: The cluster IDs of the primary and standby clusters. | ||
| - `"created_at"`: The time at which the PCR stream was created. |
There was a problem hiding this comment.
same q as above re: what exactly are these times, are they SQL timestamps, etc.
There was a problem hiding this comment.
They're date-time, I've linked to the timestamp docs, also the schema of the response is listed in the Cloud API docs.
There was a problem hiding this comment.
So, I've also added a link to the API ref docs in the prereq section for schema details on the responses.
|
|
||
| Status | Description | ||
| -------+------------ | ||
| `STARTING` | Setting up VPC peering between clusters and validating the connectivity. |
There was a problem hiding this comment.
link to VPC peering docs? if not pls ignore
| -------+------------ | ||
| `STARTING` | Setting up VPC peering between clusters and validating the connectivity. | ||
| `REPLICATING` | Completing an initial scan and then continuing ongoing replication between the primary and standby clusters. | ||
| `FAILING_OVER` | Initiating the failover from the primary to the standby cluster. |
There was a problem hiding this comment.
could "fail over" link to the failover section?
|
TFTRs! |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
DOC-10050
Added docs for running PCR on Cloud Advanced clusters with the API. This adds the page under the Cloud Deployments section of the docs.