Update LDR privileges for v25.2 #19518

katmayb · 2025-04-11T20:13:31Z

Fixes DOC-12962, DOC-12786

This PR updates the LDR privileges for v25.2.

Adds the REPLICATIONDEST and REPLICATIONSOURCE privilege. Deprecates the REPLICATION privilege.

Updates the SQL ref pages, tutorial for LDR, and general Auth page of privileges.

The tutorial content required some shuffling round to ensure the privilege instructions made logical sense.

Preview

Tutorial
Create logical replication stream
Create logically replicated

github-actions · 2025-04-11T20:13:58Z

Files changed:

src/current/_includes/v25.2/sql/privileges.md:

src/current/v25.2/create-logical-replication-stream.md
src/current/v25.2/create-logically-replicated.md
src/current/v25.2/set-up-logical-data-replication.md

netlify · 2025-04-11T20:14:11Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`76b77c7`
🔍 Latest deploy log	https://app.netlify.com/sites/cockroachdb-interactivetutorials-docs/deploys/681b8a5c3d28410008f0d41d

netlify · 2025-04-11T20:14:15Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`76b77c7`
🔍 Latest deploy log	https://app.netlify.com/sites/cockroachdb-api-docs/deploys/681b8a5cf6dd3e00081a3487

katmayb · 2025-04-11T20:15:02Z

src/current/v25.2/set-up-logical-data-replication.md


 <image src="{{ 'images/v25.2/bidirectional-stream.svg' | relative_url }}" alt="Diagram showing bidirectional LDR from cluster A to B and back again from cluster B to A." style="width:70%" />

 For more details on use cases, refer to the [Logical Data Replication Overview]({% link {{ page.version.version }}/logical-data-replication-overview.md %}).

+## Syntax


This is not new content, I moved this up from one of the steps. Since the privilege instructions would have preceded these syntax descriptions, it made sense to pull this Syntax section up to the introduction.

netlify · 2025-04-11T20:21:59Z

✅ Netlify Preview

Name	Link
🔨 Latest commit	`76b77c7`
🔍 Latest deploy log	https://app.netlify.com/sites/cockroachdb-docs/deploys/681b8a5cf379b20008517470
😎 Deploy Preview	https://deploy-preview-19518--cockroachdb-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

alicia-l2

This LGTM - I have a bit of confusion about which user needs which privilege - I'm going to let Michael have the final say on that though.

alicia-l2 · 2025-04-22T15:36:12Z

src/current/v25.2/create-logical-replication-stream.md

-Use the [`GRANT SYSTEM`]({% link {{ page.version.version }}/grant.md %}) statement:
+- The table-level `REPLICATIONSOURCE` privilege on the source table(s).
+
+This is the user provided in the source URI when you start a LDR stream.


Do you mean that the user provided in the source must have this privilege? This line doesn't have a bullet point on it so it was a bit confusing to read.

alicia-l2 · 2025-04-22T15:36:36Z

src/current/v25.2/create-logical-replication-stream.md

+
+On the destination cluster:
+
+- The table-level `REPLICATIONDEST` privilege on the destination table(s).


do we also need to call out that the user here should have the privilege?

msbutler

Thank you for doing this and sorry for such a slow review! I've been a bit under water lately.

msbutler · 2025-04-23T12:51:52Z

src/current/v25.2/create-logical-replication-stream.md

+
+For bidirectional LDR:
+
+- The user in the original source URI, who begins the reverse LDR stream, requires the table-level `REPLICATIONDEST` privilege.


the CREATE LOGICAL REPLICATION STREAM syntax does not automatically set up a reverse stream. so i think this line can be rephrased. For "manually set up" bidi replication, the user essentially has to do the same auth exercises on both sides. E.g.

For setting up the stream from A to B, the user passed in for the URI to A must have the REPLICATIONSOURCE priv, and the user executing the command from B, needs to have the REPLICATIONDEST priv.

For setting up the stream from B to A, the user passed in for the URI to B must have the REPLICATIONSOURCE priv, and the user executing the command from A, needs to have the REPLICATIONDEST priv.

msbutler · 2025-04-23T12:57:05Z

src/current/v25.2/create-logically-replicated.md

+
+For bidirectional LDR:
+
+- The user in the original source URI, who begins the reverse LDR stream, requires the table-level `REPLICATIONDEST` privilege.


we should also document that the user provided in the Dest URI must be the same user executing the CREATE LOGICALLY REPLICATED table cmd. For example, in this unit test:
https://github.com/jeffswenson/cockroach/blob/jeffswenson-workload-generate-decimals/pkg/crosscluster/logical/logical_replication_job_test.go#L2180
CREATE LOGICALLY REPLICATED TABLES (tab_clone_2, tab2_clone_2) FROM TABLES (tab, tab2) ON $1 WITH BIDIRECTIONAL ON $2
the user in the URI supplied at $2 must be the same user executing the CREATE LOGICALLY REPLICATED table cmd.

(I need to add a quick patch to assert this but higher priority things have gotten in the way)

msbutler · 2025-04-23T13:02:58Z

src/current/v25.2/set-up-logical-data-replication.md

+    For details on which syntax to use, refer to the [Syntax](#syntax) section at the beginning of this tutorial.
+
+    {{site.data.alerts.callout_info}}
+    If you are setting up bidirectional LDR, each cluster must **authorize both stream directions** using the table-level privileges. Ensure that you also grant privileges to users running the LDR stream in the reverse direction (from the original destination to the original source).


given my comments above on the slightly different reverse stream auth stories for bidi replication, I think this callout could be rephrased.

msbutler

This looks much clearer! Left some minor corrections.

msbutler · 2025-05-02T13:18:02Z

src/current/v25.2/create-logical-replication-stream.md

+B ➔ A | B | User in the LDR connection string. | `REPLICATIONSOURCE`
+B ➔ A | A | User running the command. | `REPLICATIONDEST`
+
+Grant a table-level privilege with the [`GRANT`]({% link {{ page.version.version }}/grant.md %}) statement to a [user or a role]({% link {{ page.version.version }}/security-reference/authorization.md %}#users-and-roles):


nit: a user can still grant these privs at the system level if they'd like. If a user was running LDR over a 1000 tables, perhaps they'd rather use the system level priv as oppose to granting the priv on each table.

msbutler · 2025-05-02T13:32:23Z

src/current/v25.2/create-logically-replicated.md

+----------------------+---------+-----------+-------------------
+A ➔ B | A | User in source connection string. | `REPLICATIONSOURCE` on A's tables.
+A ➔ B | B | User running `CREATE LOGICALLY REPLICATED` from the destination cluster. The destination table will be created and the user given the `REPLICATIONDEST` privilege on the new table automatically.<br>**Note:** Must match the user in the destination connection string for bidirectional LDR. | `CREATE` on B's parent database.
+B ➔ A (reverse stream) | B | User in the new source connection string. | `REPLICATIONSOURCE` on B's tables.


this isn't necessary. Becuase the user in the reverse stream is the user that ran the CREATE LDR stmt, it has CREATE on the database and is implicitly granted REPLICATIONSOURCE on B's tables.

Got it, removed that line!

msbutler · 2025-05-02T13:38:06Z

src/current/v25.2/create-logically-replicated.md

-Use the [`GRANT SYSTEM`]({% link {{ page.version.version }}/grant.md %}) statement:
+LDR from cluster A to B represents a _unidirectional_ setup from a source to a destination cluster. LDR from cluster B to A is the reverse stream for a _bidirectional_ setup:
+
+Replication direction | Cluster | User role | Required privileges


i think this table explains things really well, and I wonder if it should be supplemented with a toy command, especially for the bidi case:

user baz executes the following statement
CREATE LOGICALLY REPLICATED TABLES B.tab FROM TABLES A.tab ON 'uriToA/user=foo' WITH BIDIRECTIONAL ON 'uriToB/user=baz

For this to work

baz requires CREATE on database B, implicitly gets REPLICATIONDEST and REPLICATIONSOURCE on b.tab

foo requires REPLICATIONSOURCE and REPLICATIONDEST on A.tab

baz must be the user in the BIDIRECTIONAL ON uri.

Added this example under the table

msbutler

LGTM!

rmloveland

LGTM!

katmayb commented Apr 11, 2025

View reviewed changes

katmayb requested review from msbutler and alicia-l2 April 11, 2025 20:30

alicia-l2 approved these changes Apr 22, 2025

View reviewed changes

msbutler reviewed Apr 23, 2025

View reviewed changes

katmayb force-pushed the ldr-privileges-25.2 branch 4 times, most recently from f5b0559 to 29b7b42 Compare April 30, 2025 20:55

katmayb requested a review from msbutler April 30, 2025 21:02

msbutler reviewed May 2, 2025

View reviewed changes

katmayb force-pushed the ldr-privileges-25.2 branch from 29b7b42 to a9b2d1c Compare May 2, 2025 18:52

katmayb requested a review from msbutler May 2, 2025 19:30

msbutler approved these changes May 2, 2025

View reviewed changes

katmayb requested a review from rmloveland May 6, 2025 12:45

rmloveland approved these changes May 7, 2025

View reviewed changes

katmayb added 3 commits May 7, 2025 12:29

Update LDR privileges for v25.2

80c4082

Edits & feedback

2268096

Updates

76b77c7

katmayb force-pushed the ldr-privileges-25.2 branch from a9b2d1c to 76b77c7 Compare May 7, 2025 16:29

katmayb merged commit 6da99f1 into main May 7, 2025
6 checks passed

katmayb deleted the ldr-privileges-25.2 branch May 7, 2025 16:36


		On the destination cluster:

		- The table-level `REPLICATIONDEST` privilege on the destination table(s).


		For bidirectional LDR:

		- The user in the original source URI, who begins the reverse LDR stream, requires the table-level `REPLICATIONDEST` privilege.

Update LDR privileges for v25.2 #19518

Update LDR privileges for v25.2 #19518

Uh oh!

Conversation

katmayb commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview

Uh oh!

github-actions bot commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Files changed:

Uh oh!

netlify bot commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Uh oh!

netlify bot commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cockroachdb-api-docs canceled.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

netlify bot commented Apr 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Netlify Preview

Uh oh!

alicia-l2 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msbutler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msbutler left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msbutler left a comment

Choose a reason for hiding this comment

Uh oh!

rmloveland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

katmayb commented Apr 11, 2025 •

edited

Loading

github-actions bot commented Apr 11, 2025 •

edited

Loading

netlify bot commented Apr 11, 2025 •

edited

Loading

netlify bot commented Apr 11, 2025 •

edited

Loading

netlify bot commented Apr 11, 2025 •

edited

Loading