Update LDR privileges for v25.2

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

@@ -19,7 +19,9 @@ Privilege | Levels | Description
 <a id="modifyclustersetting"></a>`MODIFYCLUSTERSETTING` | System | Grants the ability to modify [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}).
 `MODIFYSQLCLUSTERSETTING` | System | Grants the ability to modify SQL [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}) (cluster settings prefixed with `sql.`).
 `NOSQLLOGIN` | System | Prevents roles from connecting to the SQL interface of a cluster.
-`REPLICATION` | System | Grants the ability to create a [logical data replication]({% link {{ page.version.version }}/logical-data-replication-overview.md %}) or [physical cluster replication]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}) stream.
+**Deprecated** `REPLICATION` | System | As of v25.2 `REPLICATION` is **deprecated**. Instead, use the `REPLICATIONSOURCE` and `REPLICATIONDEST` privileges at the table level. Grants the ability to create a [logical data replication]({% link {{ page.version.version }}/logical-data-replication-overview.md %}) or [physical cluster replication]({% link {{ page.version.version }}/physical-cluster-replication-overview.md %}) stream.
+<a id="replicationdest"></a><span class="version-tag">New in v25.2:</span>`REPLICATIONDEST` | Table | Grants the ability to run logical data replication into an existing table on the destination cluster. For more details, refer to the [Set Up Logical Data Replication]({% link {{ page.version.version }}/set-up-logical-data-replication.md %}) tutorial.
+<a id="replicationsource"></a><span class="version-tag">New in v25.2:</span> `REPLICATIONSOURCE` | Table | Grants the ability to run logical data replication from a table on the source cluster. For more details, refer to the [Set Up Logical Data Replication]({% link {{ page.version.version }}/set-up-logical-data-replication.md %}) tutorial.
 `RESTORE` | System, Database | Grants the ability to restore [backups]({% link {{ page.version.version }}/backup-and-restore-overview.md %}) at the system or database level. Refer to `RESTORE` [Required privileges]({% link {{ page.version.version }}/restore.md %}#required-privileges) for more details.
 `SELECT` | Table, Sequence | Grants the ability to run [selection queries]({% link {{ page.version.version }}/query-data.md %}) at the table or sequence level.
 `UPDATE` | Table, Sequence | Grants the ability to run [update statements]({% link {{ page.version.version }}/update-data.md %}) at the table or sequence level.

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

@@ -20,18 +20,30 @@ If the table you're replicating does not contain [user-defined types]({% link {{
 
 ## Required privileges
 
-`CREATE LOGICAL REPLICATION STREAM` requires one of the following privileges:
+`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.
 
-- The [`admin` role]({% link {{ page.version.version }}/security-reference/authorization.md %}#admin-role).
-- The [`REPLICATION` system privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#privileges).
+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.
 
-Use the [`GRANT SYSTEM`]({% link {{ page.version.version }}/grant.md %}) statement:
+{% 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:
+
+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 the privilege at the table or [system level]({% link {{ page.version.version }}/grant.md %}#grant-system-level-privileges-on-the-entire-cluster) 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):
 
 {% include_cached copy-clipboard.html %}
 ~~~ sql
-GRANT SYSTEM REPLICATION TO user;
+GRANT REPLICATIONSOURCE ON TABLE database.public.tablename TO user/role;
 ~~~
 
+{{site.data.alerts.callout_info}}
+As of v25.2, the [`REPLICATION` system privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#privileges) is **deprecated** and will be removed in a future release. Use `REPLICATIONSOURCE` and `REPLICATIONDEST` for authorization at the table level.
+{{site.data.alerts.end}}
+
 ## Synopsis
 
 <div>

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

@@ -22,18 +22,44 @@ This page is a reference for the `CREATE LOGICALLY REPLICATED` SQL statement, wh
 
 ## Required privileges
 
-`CREATE LOGICALLY REPLICATED` requires one of the following privileges:
+{% include_cached new-in.html version="v25.2" %} Users need the following privileges to create an LDR stream with `CREATE LOGICALLY REPLICATED`:
 
-- The [`admin` role]({% link {{ page.version.version }}/security-reference/authorization.md %}#admin-role).
-- The [`REPLICATION` system privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#privileges).
+- **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.
 
-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
+----------------------+---------+-----------+-------------------
+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.
+Reverse replication requirement | A | Original source connection string user. | `REPLICATIONDEST` on A's tables.
+
+For example, the user `maxroach` will run the following statement to start LDR on the destination cluster:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+CREATE LOGICALLY REPLICATED TABLE B.table FROM TABLE A.table ON 'A_connection_string/user=samroach' WITH BIDIRECTIONAL ON 'B_connection_string/user=maxroach;
+~~~
+
+To start LDR successfully with this statement:
+
+- `maxroach` requires `CREATE` on database B, implicitly gets `REPLICATIONDEST` and `REPLICATIONSOURCE` on `B.table`.
+- `samroach` requires `REPLICATIONSOURCE` and `REPLICATIONDEST` on `A.table`.
+- `maxroach` must be the user in the `BIDIRECTIONAL ON` connection string.
+
+Grant the privilege at the table or [system level]({% link {{ page.version.version }}/grant.md %}#grant-system-level-privileges-on-the-entire-cluster) 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):
 
 {% include_cached copy-clipboard.html %}
 ~~~ sql
-GRANT SYSTEM REPLICATION TO user;
+GRANT REPLICATIONSOURCE ON TABLE database.public.tablename TO user/role;
 ~~~
 
+{{site.data.alerts.callout_info}}
+As of v25.2, the [`REPLICATION` system privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#privileges) is **deprecated** and will be removed in a future release. Use `REPLICATIONSOURCE` and `REPLICATIONDEST` for authorization at the table level.
+{{site.data.alerts.end}}
+
 ## Synopsis
 
 <div>

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

@@ -15,14 +15,24 @@ In this tutorial, you will set up [**logical data replication (LDR)**]({% link {
 - _Unidirectional_ LDR from a source table to a destination table (cluster A to cluster B) in one LDR job.
 - _Bidirectional_ LDR for the same table from cluster A to cluster B and from cluster B to cluster A. In a bidirectional setup, each cluster operates as both a source and a destination in separate LDR jobs.
 
-Create the new table on the destination cluster automatically and conduct a fast, offline initial scan with the [`CREATE LOGICALLY REPLICATED`]({% link {{ page.version.version }}/create-logically-replicated.md %}) syntax. `CREATE LOGICALLY REPLICATED` accepts `unidirectional` or `bidirectional on` as an option in order to create one of the setups automatically. [Step 3](#step-3-start-ldr) outlines when to use the `CREATE LOGICALLY REPLICATED` or the `CREATE LOGICAL REPLICATION STREAM` syntax to start LDR.
-
-In the following diagram, **LDR stream 1** creates a unidirectional LDR setup, introducing **LDR stream 2** extends the setup to bidirectional.
+In the following diagram, **LDR stream 1** creates a unidirectional LDR setup. Introducing **LDR stream 2** extends the setup to bidirectional.
 
 <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
+
+LDR streams can be started using one of the following SQL statements, depending on your requirements:
+
+- [`CREATE LOGICALLY REPLICATED`]({% link {{ page.version.version }}/create-logically-replicated.md %}): Creates the new table on the destination cluster automatically, and conducts a fast, offline initial scan. `CREATE LOGICALLY REPLICATED` accepts `unidirectional` or `bidirectional on` as an option in order to create either one of the setups automatically. **The table cannot contain [user-defined types]({% link {{ page.version.version }}/enum.md %}) or [foreign key]({% link {{ page.version.version }}/foreign-key.md %}) dependencies.** Follow [these steps](#create-logically-replicated) for setup instructions.
+- [`CREATE LOGICAL REPLICATION STREAM`]({% link {{ page.version.version }}/create-logical-replication-stream.md %}): Starts the LDR stream after you've created the matching table on the destination cluster. **If the table contains user-defined types or foreign key dependencies, you must use this syntax.** Allows for manual creation of unidirectional or bidirectional LDR. Follow [these steps](#create-logical-replication-stream) for setup instructions.
+
+Also, for both SQL statements, note:
+
+- It is necessary to use the [fully qualified]({% link {{ page.version.version }}/sql-name-resolution.md %}) table name for the source table and destination table in the statement.
+- {% include {{ page.version.version }}/ldr/multiple-tables.md %}
+
 ## Tutorial overview
 
 If you're setting up bidirectional LDR, both clusters will act as a source and a destination in the respective LDR jobs. The high-level steps for setting up bidirectional or unidirectional LDR:
@@ -53,7 +63,7 @@ You cannot use LDR on a table with a schema that contains:
 - Indexes with a [virtual computed column]({% link {{ page.version.version }}/computed-columns.md %})
 - Composite types in the [primary key]({% link {{ page.version.version }}/primary-key.md %})
 
-Additionally, for the `CREATE LOGICALLY REPLCATED` syntax, you cannot use LDR on a table with a schema that contains:
+Additionally, for the `CREATE LOGICALLY REPLICATED` syntax, you cannot use LDR on a table with a schema that contains:
 
 - [User-defined types]({% link {{ page.version.version }}/enum.md %}) 
 - [Foreign key]({% link {{ page.version.version }}/foreign-key.md %}) dependencies
@@ -84,19 +94,43 @@ If you are setting up bidirectional LDR, you **must** run this step on both clus
     SET CLUSTER SETTING kv.rangefeed.enabled = true;
     ~~~
 
-1. On the **destination**, create a user with the [`REPLICATION` system privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) who will start the LDR job:
+1. On the **destination**, create a user who will start the LDR job:
 
     {% include_cached copy-clipboard.html %}
-    ~~~ sql
-    CREATE USER {your username} WITH PASSWORD '{your password}';
+    ~~~sql
+    CREATE USER {your_username} WITH PASSWORD '{your_password}';
     ~~~
 
+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:
+
+        {% 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:
+
+        {% include_cached copy-clipboard.html %}
+        ~~~sql
+        GRANT CREATE ON DATABASE {your_db} TO {your_username};
+        ~~~
+
+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 SYSTEM REPLICATION TO {your username};
+    ~~~sql
+    GRANT REPLICATIONSOURCE ON TABLE {your_db}.{your_schema}.{your_table} TO {your_username};
     ~~~
 
-    To change the password later, refer to [`ALTER USER`]({% link {{ page.version.version }}/alter-user.md %}).
+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}}
+
+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
 
@@ -157,17 +191,10 @@ In this step, you'll start the LDR stream(s) from the destination cluster. You c
 - `immediate` (default): {% include {{ page.version.version }}/ldr/immediate-description.md %}
 - `validated`: {% include {{ page.version.version }}/ldr/validated-description.md %}
 
-### Syntax
-
-LDR streams can be started using one of the following SQL statements, depending on your requirements:
-
-- [`CREATE LOGICALLY REPLICATED`]({% link {{ page.version.version }}/create-logically-replicated.md %}): Creates the new table on the destination cluster automatically, and conducts a fast, offline initial scan. `CREATE LOGICALLY REPLICATED` accepts `unidirectional` or `bidirectional on` as an option in order to create either one of the setups automatically. **The table cannot contain a [user-defined types]({% link {{ page.version.version }}/enum.md %}) or [foreign key]({% link {{ page.version.version }}/foreign-key.md %}) dependencies.** Follow [these steps](#create-logically-replicated) for setup instructions.
-- [`CREATE LOGICAL REPLICATION STREAM`]({% link {{ page.version.version }}/create-logical-replication-stream.md %}): Starts the LDR stream after you've created the matching table on the destination cluster. **If the table contains user-defined types or foreign key dependencies, you must use this syntax.** Allows for manual creation of unidirectional or bidirectional LDR. Follow [these steps](#create-logical-replication-stream) for setup instructions.
+LDR streams can be started using one of the following sections for instructions on creating an LDR stream. For details on which syntax to use, refer to the [Syntax](#syntax) section at the beginning of this tutorial:
 
-Also, for both SQL statements, note:
-
-- It is necessary to use the [fully qualified]({% link {{ page.version.version }}/sql-name-resolution.md %}) table name for the source table and destination table in the statement.
-- {% include {{ page.version.version }}/ldr/multiple-tables.md %}
+- [`CREATE LOGICALLY REPLICATED`](#create-logically-replicated)
+- [`CREATE LOGICAL REPLICATION STREAM`](#create-logical-replication-stream)
 
 #### `CREATE LOGICALLY REPLICATED`
 
@@ -182,7 +209,7 @@ Use `CREATE LOGICALLY REPLICATED` to create either a unidirectional or bidirecti
 
 - Bidirectional LDR: This statement will first create the LDR jobs for the first stream. You must run it from the **destination** cluster that does not contain the table. Once the offline initial scan completes, the reverse stream will be initialized so that the original destination cluster can send changes to the original source.
 
-    Run the following from the **destination** cluster (i.e, the cluster that does not have the table currently):
+    Run the following from the **destination** cluster (i.e., the cluster that currently does not have the table):
 
     {% include_cached copy-clipboard.html %}
     ~~~ sql
@@ -237,7 +264,7 @@ If you're setting up bidirectional LDR, both clusters will have a history retent
 
 ### DB Console
 
-You'll access the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) and monitor the status and metrics for the created LDR jobs. Depending on which cluster you would like to view, follow the instructions for either the source or destination.
+You can access the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) and monitor the status and metrics for the created LDR jobs. Depending on which cluster you would like to view, follow the instructions for either the source or destination.
 
 {{site.data.alerts.callout_success}}
 You can use the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}), the SQL shell, [Metrics Export]({% link {{ page.version.version }}/datadog.md %}#enable-metrics-collection) with Prometheus and Datadog, and [labels with some LDR metrics]({% link {{ page.version.version }}/multi-dimensional-metrics.md %}) to monitor the job.