From d737648288783c916ad321217d6cfda2b59476d6 Mon Sep 17 00:00:00 2001 From: Kathryn May Date: Mon, 16 Dec 2024 10:53:28 -0500 Subject: [PATCH] Add further link reference in LDR docs --- src/current/v24.3/create-logical-replication-stream.md | 8 ++++---- src/current/v24.3/logical-data-replication-overview.md | 2 +- .../v24.3/physical-cluster-replication-overview.md | 4 ++++ src/current/v24.3/set-up-logical-data-replication.md | 10 +++++----- 4 files changed, 14 insertions(+), 10 deletions(-) diff --git a/src/current/v24.3/create-logical-replication-stream.md b/src/current/v24.3/create-logical-replication-stream.md index 8c3832678e5..3e7fb81a8e6 100644 --- a/src/current/v24.3/create-logical-replication-stream.md +++ b/src/current/v24.3/create-logical-replication-stream.md @@ -48,9 +48,9 @@ Parameter | Description Option | Description -------+------------ `cursor` | Emits any changes after the specified timestamp. LDR will not perform an initial backfill with the `cursor` option, it will stream any changes after the specified timestamp. The LDR job will encounter an error if you specify a `cursor` timestamp that is before the configured [garbage collection]({% link {{ page.version.version }}/architecture/storage-layer.md %}#garbage-collection) window for that table. **Warning:** Apply the `cursor` option carefully to LDR streams. Using a timestamp in error could cause data loss. -`discard` | (**Unidirectional LDR only**) Ignore [TTL deletes]({% link {{ page.version.version }}/row-level-ttl.md %}) in an LDR stream with `discard = ttl-deletes`. **Note**: To ignore row-level TTL deletes in an LDR stream, it is necessary to set the [`ttl_disable_changefeed_replication`]({% link {{ page.version.version }}/row-level-ttl.md %}#ttl-storage-parameters) storage parameter on the source table. Refer to the [Ignore row-level TTL deletes](#ignore-row-level-ttl-deletes) example. +`discard` | ([**Unidirectional LDR only**]({% link {{ page.version.version }}/logical-data-replication-overview.md %}#use-cases)) Ignore [TTL deletes]({% link {{ page.version.version }}/row-level-ttl.md %}) in an LDR stream with `discard = ttl-deletes`. **Note**: To ignore row-level TTL deletes in an LDR stream, it is necessary to set the [`ttl_disable_changefeed_replication`]({% link {{ page.version.version }}/row-level-ttl.md %}#ttl-storage-parameters) storage parameter on the source table. Refer to the [Ignore row-level TTL deletes](#ignore-row-level-ttl-deletes) example. `label` | Tracks LDR metrics at the job level. Add a user-specified string with `label`. Refer to [Metrics labels]({% link {{ page.version.version }}/logical-data-replication-monitoring.md %}#metrics-labels). -`mode` | Determines how LDR replicates the data to the destination cluster. Possible values: `immediate`, `validated`. For more details refer to [LDR modes](#ldr-modes). +`mode` | Determines how LDR replicates the data to the destination cluster. Possible values: `immediate`, `validated`. For more details, refer to [LDR modes](#ldr-modes). ## LDR modes @@ -61,13 +61,13 @@ _Modes_ determine how LDR replicates the data to the destination cluster. There ## Bidirectional LDR -_Bidirectional_ LDR consists of two clusters with two LDR jobs running in opposite directions between the clusters. If you're setting up bidirectional LDR, both clusters will act as a source and a destination in the respective LDR jobs. +_Bidirectional_ LDR consists of two clusters with two LDR jobs running in opposite directions between the clusters. If you're setting up [bidirectional LDR]({% link {{ page.version.version }}/logical-data-replication-overview.md %}#use-cases), both clusters will act as a source and a destination in the respective LDR jobs. LDR supports starting with two empty tables, or one non-empty table. LDR does **not** support starting with two non-empty tables. When you set up bidirectional LDR, if you're starting with one non-empty table, start the first LDR job from empty to non-empty table. Therefore, you would run `CREATE LOGICAL REPLICATION STREAM` from the destination cluster where the non-empty table exists. ## Examples -To start LDR, you must run the `CREATE LOGICAL REPLICATION STREAM` statement from the **destination** cluster. Use the[ fully qualified table name(s)]({% link {{ page.version.version }}/sql-name-resolution.md %}#how-name-resolution-works) and ensure that the source and destination table names are identical. The following examples show statement usage with different options and use cases. +To start LDR, you must run the `CREATE LOGICAL REPLICATION STREAM` statement from the **destination** cluster. Use the [fully qualified table name(s)]({% link {{ page.version.version }}/sql-name-resolution.md %}#how-name-resolution-works). The following examples show statement usage with different options and use cases. ### Start an LDR stream diff --git a/src/current/v24.3/logical-data-replication-overview.md b/src/current/v24.3/logical-data-replication-overview.md index 69df26a4707..7495991c39f 100644 --- a/src/current/v24.3/logical-data-replication-overview.md +++ b/src/current/v24.3/logical-data-replication-overview.md @@ -44,7 +44,7 @@ Isolate critical application workloads from non-critical application workloads. - **Table-level replication**: When you initiate LDR, it will replicate all of the source table's existing data to the destination table. From then on, LDR will replicate the source table's data to the destination table to achieve eventual consistency. - **Last write wins conflict resolution**: LDR uses [_last write wins (LWW)_ conflict resolution]({% link {{ page.version.version }}/manage-logical-data-replication.md %}#conflict-resolution), which will use the latest [MVCC]({% link {{ page.version.version }}/architecture/storage-layer.md %}#mvcc) timestamp to resolve a conflict in row insertion. - **Dead letter queue (DLQ)**: When LDR starts, the job will create a [DLQ table]({% link {{ page.version.version }}/manage-logical-data-replication.md %}#dead-letter-queue-dlq) with each replicating table in order to track unresolved conflicts. You can interact and manage this table like any other SQL table. -- **Replication modes**: LDR offers different _modes_ that apply data differently during replication, which allows you to consider optimizing for throughput or constraints during replication. +- **Replication modes**: LDR offers different [_modes_]({% link {{ page.version.version }}/create-logical-replication-stream.md %}#ldr-modes) that apply data differently during replication, which allows you to consider optimizing for throughput or constraints during replication. - **Monitoring**: To [monitor]({% link {{ page.version.version }}/logical-data-replication-monitoring.md %}) LDR's initial progress, current status, and performance, you can view metrics available in the DB Console, Prometheus, and Metrics Export. ## Get started diff --git a/src/current/v24.3/physical-cluster-replication-overview.md b/src/current/v24.3/physical-cluster-replication-overview.md index 179281f9b57..bd59c819079 100644 --- a/src/current/v24.3/physical-cluster-replication-overview.md +++ b/src/current/v24.3/physical-cluster-replication-overview.md @@ -15,6 +15,10 @@ In a disaster recovery scenario, you can [_fail over_]({% link {{ page.version.v For a list of requirements for PCR, refer to the [Before you begin]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}#before-you-begin) section of the [setup tutorial]({% link {{ page.version.version }}/set-up-physical-cluster-replication.md %}). +{{site.data.alerts.callout_success}} +Cockroach Labs also has a [logical data replication]({% link {{ page.version.version }}/logical-data-replication-overview.md %}) tool that continuously replicates tables between an active _source_ CockroachDB cluster to an active _destination_ CockroachDB cluster. Both source and destination can receive application reads and writes, and participate in [_bidirectional_]({% link {{ page.version.version }}/logical-data-replication-overview.md %}#use-cases) LDR for eventual consistency in the replicating tables. +{{site.data.alerts.end}} + ## Use cases You can use PCR in a disaster recovery plan to: diff --git a/src/current/v24.3/set-up-logical-data-replication.md b/src/current/v24.3/set-up-logical-data-replication.md index be66a1ee062..f8b9baf6ac1 100644 --- a/src/current/v24.3/set-up-logical-data-replication.md +++ b/src/current/v24.3/set-up-logical-data-replication.md @@ -10,7 +10,7 @@ toc: true Logical data replication is only supported in CockroachDB {{ site.data.products.core }} clusters. {{site.data.alerts.end}} -In this tutorial, you will set up **logical data replication (LDR)** streaming data from a source table to a destination table between two CockroachDB clusters. Both clusters are active and can serve traffic. You can apply the outlined steps to create _unidirectional_ LDR from a source table to a destination table (cluster A to cluster B) in one LDR job. Optionally, you can also create _bidirectional_ LDR from cluster B's table to cluster A's table by starting a second LDR job. In a bidirectional setup, each cluster operates as both a source and a destination in separate LDR jobs. +In this tutorial, you will set up [**logical data replication (LDR)**]({% link {{ page.version.version }}/logical-data-replication-overview.md %}) streaming data from a source table to a destination table between two CockroachDB clusters. Both clusters are active and can serve traffic. You can apply the outlined steps to create _unidirectional_ LDR from a source table to a destination table (cluster A to cluster B) in one LDR job. Optionally, you can also create _bidirectional_ LDR from cluster B's table to cluster A's table by starting a second LDR job. In a bidirectional setup, each cluster operates as both a source and a destination in separate LDR jobs. For more details on use cases, refer to the [Logical Data Replication Overview]({% link {{ page.version.version }}/logical-data-replication-overview.md %}). @@ -55,7 +55,7 @@ You cannot use LDR on a table with a schema that contains the following: For more details, refer to the LDR [Known limitations]({% link {{ page.version.version }}/logical-data-replication-overview.md %}#known-limitations). -When you run LDR in `immediate` mode, you cannot replicate a table with [foreign key constraints]({% link {{ page.version.version }}/foreign-key.md %}). In `validated` mode, foreign key constraints **must** match. All constraints are enforced at the time of SQL/application write. +When you run LDR in [`immediate` mode](#modes), you cannot replicate a table with [foreign key constraints]({% link {{ page.version.version }}/foreign-key.md %}). In [`validated` mode](#modes), foreign key constraints **must** match. All constraints are enforced at the time of SQL/application write. ## Step 1. Prepare the cluster @@ -66,7 +66,7 @@ When you run LDR in `immediate` mode, you cannot replicate a table with [foreign cockroach sql --url "postgresql://root@{node IP or hostname}:26257?sslmode=verify-full" --certs-dir=certs ~~~ -1. Enable the `kv.rangefeed.enabled` cluster setting on the **source** cluster: +1. Enable the `kv.rangefeed.enabled` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) on the **source** cluster: {% include_cached copy-clipboard.html %} ~~~ sql @@ -85,7 +85,7 @@ When you run LDR in `immediate` mode, you cannot replicate a table with [foreign GRANT SYSTEM REPLICATION TO {your username}; ~~~ - If you need to change the password later, refer to [`ALTER USER`]({% link {{ page.version.version }}/alter-user.md %}). {% comment %}Add link to https://www.cockroachlabs.com/docs/stable/ui-overview#db-console-security-considerations for secure clusters{% endcomment %} + If you need to change the password later, refer to [`ALTER USER`]({% link {{ page.version.version }}/alter-user.md %}). ## Step 2. Connect from the destination to the source @@ -117,7 +117,7 @@ You can use the `cockroach encode-uri` command to generate a connection string c In this step, you'll start the LDR job from the destination cluster. You can replicate one or multiple tables in a single LDR job. You cannot replicate system tables in LDR, which means that you must manually apply configurations and cluster settings, such as [row-level TTL]({% link {{ page.version.version }}/row-level-ttl.md %}) and user permissions on the destination cluster. -_Modes_ determine how LDR replicates the data to the destination cluster. There are two modes: +_Modes_ determine how LDR replicates the data to the destination cluster. There are two modes: - `immediate` (default): {% include {{ page.version.version }}/ldr/immediate-description.md %} - `validated`: {% include {{ page.version.version }}/ldr/validated-description.md %}