Skip to content

Update LDR privileges for v25.2 #19518

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Update LDR privileges for v25.2 #19518

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion src/current/_includes/v25.2/sql/privileges.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
25 changes: 20 additions & 5 deletions src/current/v25.2/create-logical-replication-stream.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,18 +20,33 @@ 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:
{% 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 [`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).
On the source cluster:

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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


On the destination cluster:

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


For bidirectional LDR:

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

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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):

{% 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>
Expand Down
25 changes: 20 additions & 5 deletions src/current/v25.2/create-logically-replicated.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,18 +22,33 @@ 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" %} To run the `CREATE LOGICALLY REPLICATED` statement to create an LDR stream, the following privileges are required:

- 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).
On the source cluster:

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.

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.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)


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):

{% 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>
Expand Down
85 changes: 63 additions & 22 deletions src/current/v25.2/set-up-logical-data-replication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -84,19 +94,57 @@ 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}';
~~~

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.

{{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).
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

{{site.data.alerts.end}}

#### `CREATE LOGICAL REPLICATION STREAM` (existing destination table):

{% 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 SYSTEM REPLICATION TO {your username};
~~~sql
GRANT REPLICATIONDEST 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 %}).
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):

{% include_cached copy-clipboard.html %}
~~~sql
GRANT REPLICATIONSOURCE ON TABLE {your_db}.{your_schema}.{your_table} TO {your_username};
~~~

{{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

Expand Down Expand Up @@ -157,17 +205,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`

Expand All @@ -182,7 +223,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
Expand Down Expand Up @@ -237,7 +278,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.
Expand Down
Loading