Edits & feedback

Author: katmayb

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

@@ -20,21 +20,18 @@ If the table you're replicating does not contain [user-defined types]({% link {{
 
 ## Required privileges
 
-{% include_cached new-in.html version="v25.2" %} To run the `CREATE LOGICAL REPLICATION STREAM` statement to create an LDR stream, the following privileges are required:
-
-On the source cluster:
-
-- The table-level `REPLICATIONSOURCE` privilege on the source table(s).
+`CREATE LOGICAL REPLICATION STREAM` creates a one-way LDR stream only. To achieve bidirectional replication, you must manually create two separate streams, one in each direction, with the required privileges set on both clusters.
 
-This is the user provided in the source URI when you start a LDR stream.
+LDR from cluster A to B represents a one-way stream from a source to a destination cluster. LDR from cluster B to A is the reverse stream for a bidirectional setup.
 
-On the destination cluster:
-
-- The table-level `REPLICATIONDEST` privilege on the destination table(s).
-
-For bidirectional LDR:
+{% include_cached new-in.html version="v25.2" %} To run the `CREATE LOGICAL REPLICATION STREAM` statement to create an LDR stream, the following privileges are required:
 
-- The user in the original source URI, who begins the reverse LDR stream, requires the table-level `REPLICATIONDEST` privilege.
+LDR direction | Cluster | User role | Required privilege 
+----------------------+---------+-----------+--------------------
+A ➔ B | A | User in the LDR connection string. | `REPLICATIONSOURCE`
+A ➔ B | B | User running the command. | `REPLICATIONDEST`
+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):
 

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

@@ -22,21 +22,20 @@ This page is a reference for the `CREATE LOGICALLY REPLICATED` SQL statement, wh
 
 ## Required privileges
 
-{% include_cached new-in.html version="v25.2" %} To run the `CREATE LOGICALLY REPLICATED` statement to create an LDR stream, the following privileges are required:
+{% include_cached new-in.html version="v25.2" %} Users need the following privileges to create an LDR stream with `CREATE LOGICALLY REPLICATED`:
 
-On the source cluster:
+- **Source connection string user:** Needs the `REPLICATIONSOURCE` privilege on the source table(s). This is the user specified in the [source connection string]({% link {{ page.version.version }}/set-up-logical-data-replication.md %}#step-2-connect-from-the-destination-to-the-source) in unidirectional or bidirectional streams.
+- **User starting the LDR stream on the destination:** Must have `CREATE` on the destination database **and** be the same user that is specified in the destination connection string for a bidirectional stream. The destination table will be created and the user given the `REPLICATIONDEST` privilege on the new table automatically.
+- **For reverse (bidirectional) setup:** The original source user must have `REPLICATIONDEST` on the tables in the original source cluster.
 
-- The table-level `REPLICATIONSOURCE` privilege on the source table(s).
+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:
 
-This is the user provided in the source URI when you start a LDR stream.
-
-On the destination cluster:
-
-- `CREATE` on the parent database of the new table, which allows for the automatic table creation.
-
-For bidirectional LDR:
-
-- The user in the original source URI, who begins the reverse LDR stream, requires the table-level `REPLICATIONDEST` privilege.
+Replication direction | Cluster | User role | Required privileges
+----------------------+---------+-----------+-------------------
+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.
+Reverse replication requirement | A | Original source connection string user. | `REPLICATIONDEST` on A's tables.
 
 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):
 

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

@@ -101,45 +101,31 @@ If you are setting up bidirectional LDR, you **must** run this step on both clus
     CREATE USER {your_username} WITH PASSWORD '{your_password}';
     ~~~
 
-    Choose the appropriate privilege based on the SQL statement the user will run:
-    - [`CREATE LOGICAL REPLICATION STREAM`](#create-logical-replication-stream-existing-destination-table) (replicating into an **existing table**) 
-    - [`CREATE LOGICALLY REPLICATED`](#create-logically-replicated-automatically-creates-destination-table) (creating a **new table** as part of the replication). 
-        
-    For details on which syntax to use, refer to the [Syntax](#syntax) section at the beginning of this tutorial.
+1. Choose the appropriate privilege based on the SQL statement the user on the destination cluster will run. (For details on which syntax to use, refer to the [Syntax](#syntax) section at the beginning of this tutorial):
+    - [`CREATE LOGICAL REPLICATION STREAM`]({% link {{ page.version.version }}/create-logical-replication-stream.md %}) (replicating into an **existing table**). Grant the [`REPLICATIONDEST` privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#replicationdest) on the **destination table**, which allows the user to stream data into the existing table:
 
-    {{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).
-    {{site.data.alerts.end}}
+        {% include_cached copy-clipboard.html %}
+        ~~~sql
+        GRANT REPLICATIONDEST ON TABLE {your_db}.{your_schema}.{your_table} TO {your_username};
+        ~~~
+    - [`CREATE LOGICALLY REPLICATED`]({% link {{ page.version.version }}/create-logically-replicated.md %}) (creating a **new table** as part of the replication). Grant the [`CREATE` privilege]({% link {{ page.version.version }}/create-database.md %}#required-privileges) on the **parent database**, which allows the user to create a new table in the specified database, and the user will automatically have `REPLICATIONDEST` on the table they create:
 
-    #### `CREATE LOGICAL REPLICATION STREAM` (existing destination table):
+        {% include_cached copy-clipboard.html %}
+        ~~~sql
+        GRANT CREATE ON DATABASE {your_db} TO {your_username};
+        ~~~
 
-    {% include_cached new-in.html version="v25.2" %} Grant the [`REPLICATIONDEST` privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#replicationdest) on the **destination table**:
-
-    {% include_cached copy-clipboard.html %}
-    ~~~sql
-    GRANT REPLICATIONDEST ON TABLE {your_db}.{your_schema}.{your_table} TO {your_username};
-    ~~~
-
-    This privilege allows the user to stream data into the existing table.
-
-    #### `CREATE LOGICALLY REPLICATED` (automatically creates destination table):
-
-    {% include_cached new-in.html version="v25.2" %} Grant the [`CREATE` privilege]({% link {{ page.version.version }}/create-database.md %}#required-privileges) on the **parent database**:
-
-    {% include_cached copy-clipboard.html %}
-    ~~~sql
-    GRANT CREATE ON DATABASE {your_db} TO {your_username};
-    ~~~
-
-    This allows the user to create a new table in the specified database, and the user will automatically have `REPLICATIONDEST` on the table they create.
-
-1. {% include_cached new-in.html version="v25.2" %} On the **source**, grant the user who will be [specified in the connection string to the source cluster](#step-2-connect-from-the-destination-to-the-source) the [`REPLICATIONSOURCE` privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#replicationsource):
+1. On the **source**, grant the user who will be [specified in the connection string to the source cluster](#step-2-connect-from-the-destination-to-the-source) the [`REPLICATIONSOURCE` privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#replicationsource):
 
     {% include_cached copy-clipboard.html %}
     ~~~sql
     GRANT REPLICATIONSOURCE ON TABLE {your_db}.{your_schema}.{your_table} TO {your_username};
     ~~~
 
+1. (Optional) If you are setting up **bidirectional** LDR, each cluster must authorize both stream directions using the table-level privileges depending on the syntax you're using:
+    - [`CREATE LOGICAL REPLICATION STREAM`]({% link {{ page.version.version }}/create-logical-replication-stream.md %}) (setting up a reverse stream manually). Grant `REPLICATIONDEST` and `REPLICATIONSOURCE` to the users in the reverse direction.
+    - [`CREATE LOGICALLY REPLICATED`]({% link {{ page.version.version }}/create-logically-replicated.md %}) (setting up a bidirectional stream automatically). Grant the original source user `REPLICATIONDEST` on the tables.
+
 {{site.data.alerts.callout_info}}
 As of v25.2, the `REPLICATION` system privilege has been **deprecated** and replaced with the granular, table-level privileges: `REPLICATIONSOURCE` and `REPLICATIONDEST`.
 {{site.data.alerts.end}}