From 9279c5b099fa086a3717d58196c8d6db6f476e2e Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Tue, 6 May 2025 11:04:55 -0400 Subject: [PATCH] Update ALTER ROLE ALL explanation and links Fixes DOC-13580 --- .../known-limitations/grant-revoke-schema-changes.md | 2 +- src/current/_includes/v25.2/misc/session-vars.md | 2 +- .../_includes/v25.2/sql/disallow-full-table-scans.md | 4 ++-- .../_includes/v25.2/sql/transactions-limit-rows.md | 4 ++-- src/current/v25.2/alter-database.md | 8 +++++--- src/current/v25.2/alter-role.md | 4 +++- src/current/v25.2/online-schema-changes.md | 2 +- 7 files changed, 15 insertions(+), 11 deletions(-) diff --git a/src/current/_includes/v25.2/known-limitations/grant-revoke-schema-changes.md b/src/current/_includes/v25.2/known-limitations/grant-revoke-schema-changes.md index 2a2d076f108..cbe1cd8d3eb 100644 --- a/src/current/_includes/v25.2/known-limitations/grant-revoke-schema-changes.md +++ b/src/current/_includes/v25.2/known-limitations/grant-revoke-schema-changes.md @@ -11,7 +11,7 @@ When this session variable is enabled, any user/role management operations issue To accelerate user/role management operations across your entire application, you have the following options: 1. Set the session variable in all sessions by [passing it in the client connection string]({% link {{ page.version.version }}/connection-parameters.md %}#supported-options-parameters). -1. Apply the `allow_role_memberships_to_change_during_transaction` setting globally to an entire cluster using the [`ALTER ROLE ALL`]({% link {{ page.version.version }}/alter-role.md %}) statement: +1. Apply the `allow_role_memberships_to_change_during_transaction` setting globally to an entire cluster using the [`ALTER ROLE ALL`]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users) statement: {% include_cached copy-clipboard.html %} ~~~ sql diff --git a/src/current/_includes/v25.2/misc/session-vars.md b/src/current/_includes/v25.2/misc/session-vars.md index 20dc9bc7be5..2a89b74ad85 100644 --- a/src/current/_includes/v25.2/misc/session-vars.md +++ b/src/current/_includes/v25.2/misc/session-vars.md @@ -2,7 +2,7 @@ |---|---|---|---|---| | `always_distribute_full_scans` | When set to `on`, full table scans are always [distributed]({% link {{ page.version.version }}/architecture/sql-layer.md %}#distsql). | `off` | Yes | Yes | | `application_name` | The current application name for statistics collection. | Empty string, or `cockroach` for sessions from the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}). | Yes | Yes | -| `autocommit_before_ddl` | When the [`autocommit_before_ddl` session setting]({% link {{page.version.version}}/set-vars.md %}#autocommit-before-ddl) is set to `on`, any schema change statement that is sent during an [explicit transaction]({% link {{page.version.version}}/transactions.md %}) will cause the transaction to [commit]({% link {{page.version.version}}/commit-transaction.md %}) before executing the schema change. This is useful because [CockroachDB does not fully support multiple schema changes in a single transaction]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions). : This setting is enabled by default. To disable it for all [roles]({% link {{ page.version.version }}/alter-role.md %}), issue the following statement: `ALTER ROLE ALL SET autocommit_before_ddl = false` | `on` | Yes | Yes | +| `autocommit_before_ddl` | When the [`autocommit_before_ddl` session setting]({% link {{page.version.version}}/set-vars.md %}#autocommit-before-ddl) is set to `on`, any schema change statement that is sent during an [explicit transaction]({% link {{page.version.version}}/transactions.md %}) will cause the transaction to [commit]({% link {{page.version.version}}/commit-transaction.md %}) before executing the schema change. This is useful because [CockroachDB does not fully support multiple schema changes in a single transaction]({% link {{ page.version.version }}/online-schema-changes.md %}#schema-changes-within-transactions). : This setting is enabled by default. To disable it for [all roles]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users), issue the following statement: `ALTER ROLE ALL SET autocommit_before_ddl = false` | `on` | Yes | Yes | | `bytea_output` | The [mode for conversions from `STRING` to `BYTES`]({% link {{ page.version.version }}/bytes.md %}#supported-conversions). | hex | Yes | Yes | | `client_min_messages` | The severity level of notices displayed in the [SQL shell]({% link {{ page.version.version }}/cockroach-sql.md %}). Accepted values include `debug5`, `debug4`, `debug3`, `debug2`, `debug1`, `log`, `notice`, `warning`, and `error`. | `notice` | Yes | Yes | | `copy_from_atomic_enabled` | If set to `on`, [`COPY FROM`]({% link {{ page.version.version }}/copy.md %}) statements are committed atomically, matching PostgreSQL behavior. If set to `off`, `COPY FROM` statements are segmented into batches of 100 rows unless issued within an explicit transaction, matching the CockroachDB behavior in versions prior to v22.2. | `on` | Yes | Yes | diff --git a/src/current/_includes/v25.2/sql/disallow-full-table-scans.md b/src/current/_includes/v25.2/sql/disallow-full-table-scans.md index 57701770065..0e83d177878 100644 --- a/src/current/_includes/v25.2/sql/disallow-full-table-scans.md +++ b/src/current/_includes/v25.2/sql/disallow-full-table-scans.md @@ -1,4 +1,4 @@ -- At the cluster level, set `disallow_full_table_scans` for some or all users and roles. For example: +- At the cluster level, set `disallow_full_table_scans` for some or [all users and roles]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users). For example: {% include_cached copy-clipboard.html %} ~~~ sql @@ -9,4 +9,4 @@ If you disable full scans, you can set the [`large_full_scan_rows` session variable]({% link {{ page.version.version }}/set-vars.md %}#large-full-scan-rows) to specify the maximum table size allowed for a full scan. If no alternative plan is possible, the optimizer will return an error. -If you disable full scans, and you provide an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection), the optimizer will try to avoid a full scan while also respecting the index hint. If this is not possible, the optimizer will return an error. If you do not provide an index hint and it is not possible to avoid a full scan, the optimizer will return an error, the full scan will be logged, and the `sql.guardrails.full_scan_rejected.count` [metric]({% link {{ page.version.version }}/ui-overview-dashboard.md %}) will be updated. \ No newline at end of file +If you disable full scans, and you provide an [index hint]({% link {{ page.version.version }}/indexes.md %}#selection), the optimizer will try to avoid a full scan while also respecting the index hint. If this is not possible, the optimizer will return an error. If you do not provide an index hint and it is not possible to avoid a full scan, the optimizer will return an error, the full scan will be logged, and the `sql.guardrails.full_scan_rejected.count` [metric]({% link {{ page.version.version }}/ui-overview-dashboard.md %}) will be updated. diff --git a/src/current/_includes/v25.2/sql/transactions-limit-rows.md b/src/current/_includes/v25.2/sql/transactions-limit-rows.md index 0962a211195..43779b95969 100644 --- a/src/current/_includes/v25.2/sql/transactions-limit-rows.md +++ b/src/current/_includes/v25.2/sql/transactions-limit-rows.md @@ -1,4 +1,4 @@ -- When the `transaction_rows_read_err` [session setting]({% link {{ page.version.version }}/set-vars.md %}#transaction-rows-read-err) is enabled, transactions that read more than the specified number of rows will fail. In addition, the [optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}) will not create query plans with scans that exceed the specified row limit. For example, to set a default value for all users at the cluster level: +- When the `transaction_rows_read_err` [session setting]({% link {{ page.version.version }}/set-vars.md %}#transaction-rows-read-err) is enabled, transactions that read more than the specified number of rows will fail. In addition, the [optimizer]({% link {{ page.version.version }}/cost-based-optimizer.md %}) will not create query plans with scans that exceed the specified row limit. For example, to set a default value for [all users]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users) at the cluster level: {% include_cached copy-clipboard.html %} ~~~ sql @@ -12,4 +12,4 @@ ALTER ROLE ALL SET transaction_rows_written_err = 1000; ~~~ -To assess the impact of configuring these session settings, use the corresponding session settings [`transaction_rows_read_log`]({% link {{ page.version.version }}/set-vars.md %}#transaction-rows-read-log) and [`transaction_rows_written_log`]({% link {{ page.version.version }}/set-vars.md %}#transaction-rows-written-log) to log transactions that read or write the specified number of rows. Transactions are logged to the [`SQL_PERF`]({% link {{ page.version.version }}/logging.md %}#sql_perf) channel. \ No newline at end of file +To assess the impact of configuring these session settings, use the corresponding session settings [`transaction_rows_read_log`]({% link {{ page.version.version }}/set-vars.md %}#transaction-rows-read-log) and [`transaction_rows_written_log`]({% link {{ page.version.version }}/set-vars.md %}#transaction-rows-written-log) to log transactions that read or write the specified number of rows. Transactions are logged to the [`SQL_PERF`]({% link {{ page.version.version }}/logging.md %}#sql_perf) channel. diff --git a/src/current/v25.2/alter-database.md b/src/current/v25.2/alter-database.md index ee9731536c0..a40ccb0ba48 100644 --- a/src/current/v25.2/alter-database.md +++ b/src/current/v25.2/alter-database.md @@ -44,8 +44,8 @@ Subcommand | Description [`OWNER TO`](#owner-to) | Change the owner of a database. [`PLACEMENT`](#placement) | Configure the replica placement policy for a [multi-region database]({% link {{ page.version.version }}/multiregion-overview.md %}). [`RENAME TO`](#rename-to) | Change the name of a database. -[`RESET {session variable}`](#reset-session-variable) | Reset the session variable values for the database to the system defaults. This syntax is identical to [`ALTER ROLE ALL IN DATABASE ... RESET {session variable}`]({% link {{ page.version.version }}/alter-role.md %}). -[`SET {session variable}`](#set-session-variable) | Set the default session variable values for the database. This syntax is identical to [`ALTER ROLE ALL IN DATABASE ... SET {session variable}`]({% link {{ page.version.version }}/alter-role.md %}). +[`RESET {session variable}`](#reset-session-variable) | Reset the session variable values for the database to the system defaults. This syntax is identical to [`ALTER ROLE ALL IN DATABASE ... RESET {session variable}`]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users). +[`SET {session variable}`](#set-session-variable) | Set the default session variable values for the database. This syntax is identical to [`ALTER ROLE ALL IN DATABASE ... SET {session variable}`]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users). [`SET PRIMARY REGION`](#set-primary-region) | Set the primary region of a [multi-region database]({% link {{ page.version.version }}/multiregion-overview.md %}). [`SET SECONDARY REGION`](#set-secondary-region) | Set the [secondary region of a multi-region database]({% link {{ page.version.version }}/multiregion-overview.md %}#secondary-regions) for failover purposes. [`SURVIVE {ZONE,REGION} FAILURE`](#survive-zone-region-failure) | Add a survival goal to a [multi-region database]({% link {{ page.version.version }}/multiregion-overview.md %}). @@ -369,7 +369,7 @@ For usage, see [Synopsis](#synopsis). In CockroachDB, the following are aliases for `ALTER DATABASE ... RESET {session variable}`: -- [`ALTER ROLE ALL IN DATABASE ... RESET {session variable}`]({% link {{ page.version.version }}/alter-role.md %}) +- [`ALTER ROLE ALL IN DATABASE ... RESET {session variable}`]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users) ### `SET {session variable}` @@ -398,6 +398,8 @@ In CockroachDB, the following are aliases for `ALTER DATABASE ... SET {session v - `ALTER ROLE ALL IN DATABASE ... SET {session variable}` +For more information, see [`ALTER ROLE ALL ...`]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users). + ### `SET PRIMARY REGION` `ALTER DATABASE .. SET PRIMARY REGION` sets the primary [region]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions) of a [multi-region database]({% link {{ page.version.version }}/multiregion-overview.md %}). diff --git a/src/current/v25.2/alter-role.md b/src/current/v25.2/alter-role.md index eb644b6d4ec..7bb1c2eec35 100644 --- a/src/current/v25.2/alter-role.md +++ b/src/current/v25.2/alter-role.md @@ -33,7 +33,7 @@ Parameter | Description `SET {session variable}` | Set default [session variable]({% link {{ page.version.version }}/set-vars.md %}) values for a role. `RESET {session variable}`
`RESET ALL` | Reset one session variable or all session variables to the default value. `IN DATABASE database_name` | Specify a database for which to apply session variable defaults.
When `IN DATABASE` is not specified, the default session variable values apply for a role in all databases.
In order for a session to initialize session variable values to database defaults, the database must be specified as a [connection parameter]({% link {{ page.version.version }}/connection-parameters.md %}). Database default values will not appear if the database is set after connection with `USE `/`SET database=`. -`ROLE ALL ...`/`USER ALL ...` | Apply session variable settings to all roles.
Exception: The `root` user is exempt from session variable settings. +`ROLE ALL ...`/`USER ALL ...` | Apply session variable settings to all roles.
Exception: The `root` user is exempt from session variable settings. This is a failsafe; if you make a mistake with a session variable setting, you can still login as `root` and be unaffected. ### Role options @@ -255,6 +255,8 @@ ALTER ROLE ALL SET sql.spatial.experimental_box2d_comparison_operators.enabled = ALTER ROLE ~~~ +The `root` user is exempt from session variable settings changes. This is a failsafe; if you make a mistake with a session variable setting, you can still login as `root` and be unaffected. + {% include {{page.version.version}}/sql/sql-defaults-cluster-settings-deprecation-notice.md %} {% include {{page.version.version}}/sql/show-default-session-variables-for-role.md %} diff --git a/src/current/v25.2/online-schema-changes.md b/src/current/v25.2/online-schema-changes.md index 9624b8c3119..395d6c3b920 100644 --- a/src/current/v25.2/online-schema-changes.md +++ b/src/current/v25.2/online-schema-changes.md @@ -223,7 +223,7 @@ To enable this setting for the current [session]({% link {{ page.version.version SET autocommit_before_ddl = on; ~~~ -To enable it for all [users]({% link {{ page.version.version }}/alter-role.md %}): +To enable it for [all users]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users): {% include_cached copy-clipboard.html %} ~~~ sql