Alter RBR locality is blocked by sql_safe_updates

Fixes DOC-14722

Author: rmloveland

src/current/_includes/v25.4/misc/session-vars.md

@@ -75,7 +75,7 @@
 | <a id="server-version-num"></a> `server_version_num` | The version of PostgreSQL that CockroachDB emulates. | Version-dependent | Yes | Yes |
 | <a id="session-id"></a> `session_id` | The ID of the current session. | Session-dependent | No | Yes |
 | <a id="session-user"></a> `session_user` | The user connected for the current session. | User in connection string | No | Yes |
-| <a id="sql-safe-updates"></a> `sql_safe_updates` | If `true`, the following potentially unsafe SQL statements are disallowed: [`DROP DATABASE`]({% link {{ page.version.version }}/drop-database.md %}) of a non-empty database and all dependent objects; [`DELETE`]({% link {{ page.version.version }}/delete.md %}) and [`UPDATE`]({% link {{ page.version.version }}/update.md %}) without a `WHERE` clause, unless a [`LIMIT`]({% link {{ page.version.version }}/limit-offset.md %}) clause is included; [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) and [`SELECT ... FOR SHARE`]({% link {{ page.version.version }}/select-for-update.md %}) without a `WHERE` or [`LIMIT`]({% link {{ page.version.version }}/limit-offset.md %}) clause; and [`ALTER TABLE ... DROP COLUMN`]({% link {{ page.version.version }}/alter-table.md %}#drop-column).<br/>For more details, refer to [Allow potentially unsafe SQL statements]({% link {{ page.version.version }}/cockroach-sql.md %}#allow-potentially-unsafe-sql-statements). | `true` for interactive sessions from the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}), <br/>`false` for sessions from other clients | Yes | Yes |
+| <a id="sql-safe-updates"></a> `sql_safe_updates` | If `true`, the following potentially unsafe SQL statements are disallowed: [`DROP DATABASE`]({% link {{ page.version.version }}/drop-database.md %}) of a non-empty database and all dependent objects; [`DELETE`]({% link {{ page.version.version }}/delete.md %}) and [`UPDATE`]({% link {{ page.version.version }}/update.md %}) without a `WHERE` clause, unless a [`LIMIT`]({% link {{ page.version.version }}/limit-offset.md %}) clause is included; [`SELECT ... FOR UPDATE`]({% link {{ page.version.version }}/select-for-update.md %}) and [`SELECT ... FOR SHARE`]({% link {{ page.version.version }}/select-for-update.md %}) without a `WHERE` or [`LIMIT`]({% link {{ page.version.version }}/limit-offset.md %}) clause; [`ALTER TABLE ... DROP COLUMN`]({% link {{ page.version.version }}/alter-table.md %}#drop-column); and converting an existing table to [`REGIONAL BY ROW`]({% link {{ page.version.version }}/alter-table.md %}#set-the-table-locality-to-regional-by-row) using `ALTER TABLE ... LOCALITY`, unless a [region column]({% link {{ page.version.version }}/alter-table.md %}#crdb_region) has already been added to the table.<br/>For more details, refer to [Allow potentially unsafe SQL statements]({% link {{ page.version.version }}/cockroach-sql.md %}#allow-potentially-unsafe-sql-statements). | `true` for interactive sessions from the [built-in SQL client]({% link {{ page.version.version }}/cockroach-sql.md %}), <br/>`false` for sessions from other clients | Yes | Yes |
 | <a id="statement-timeout"></a> `statement_timeout` | The amount of time a statement can run before being stopped. <br/>This value can be an `int` (e.g., `10`) and will be interpreted as milliseconds. It can also be an interval or string argument, where the string can be parsed as a valid interval (e.g., `'4s'`). <br/>A value of `0` turns it off. | The value set by the `sql.defaults.statement_timeout` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) (`0s`, by default). | Yes | Yes |
 | <a id="stub-catalog-tables"></a> `stub_catalog_tables` | If `off`, querying an unimplemented, empty [`pg_catalog`]({% link {{ page.version.version }}/pg-catalog.md %}) table will result in an error, as is the case in v20.2 and earlier. If `on`, querying an unimplemented, empty `pg_catalog` table simply returns no rows. | `on` | Yes | Yes |
 | <a id="timezone"></a> `timezone` | The default time zone for the current session. | `UTC` | Yes | Yes |

src/current/v25.4/cockroach-sql.md

@@ -87,7 +87,7 @@ Flag | Description
 `--file <filename>`<br><br>`-f <filename>` |  Read SQL statements from `<filename>`.
 <a name="sql-flag-format"></a> `--format` | How to display table rows printed to the standard output. Possible values: `tsv`, `csv`, `table`, `raw`, `records`, `sql`, `html`.<br><br>**Default:** `table` for sessions that [output on a terminal](#session-and-output-types); `tsv` otherwise<br /><br />This flag corresponds to the `display_format` [client-side option](#client-side-options).
 `--read-only` | Sets the `default_transaction_read_only` [session variable]({% link {{ page.version.version }}/show-vars.md %}#supported-variables) to `on` upon connecting.
-`--safe-updates` | Disallow potentially unsafe SQL statements, including `DELETE` without a `WHERE` clause, `UPDATE` without a `WHERE` clause, and `ALTER TABLE ... DROP COLUMN`.<br><br>**Default:** `true` for [interactive sessions](#session-and-output-types); `false` otherwise<br /><br />Potentially unsafe SQL statements can also be allowed/disallowed for an entire session via the `sql_safe_updates` [session variable]({% link {{ page.version.version }}/set-vars.md %}).
+`--safe-updates` <a name="flag-safe-updates"></a> | Disallow potentially unsafe SQL statements. For the complete list of disallowed statements, refer to the documentation for the [`sql_safe_updates` session variable]({% link {{ page.version.version }}/set-vars.md %}#sql-safe-updates).<br /><br />**Default:** `true` for [interactive sessions](#session-and-output-types); `false` otherwise<br /><br />Potentially unsafe SQL statements can also be allowed/disallowed for an entire session via the [`sql_safe_updates` session variable]({% link {{ page.version.version }}/set-vars.md %}#sql-safe-updates).
 `--set` | Set a [client-side option](#client-side-options) before starting the SQL shell or executing SQL statements from the command line via `--execute`. This flag may be specified multiple times, once per option.<br><br>After starting the SQL shell, the `\set` and `unset` commands can be use to enable and disable client-side options as well.
 `--watch` | Repeat the SQL statements specified with `--execute` or `-e` until a SQL error occurs or the process is terminated. `--watch` applies to all `--execute` or `-e` flags in use.<br />You must also specify an interval at which to repeat the statement, followed by a time unit. For example, to specify an interval of 5 seconds, use `5s`.<br /><br /> Note that this flag is intended for simple monitoring scenarios during development and testing. See the [example](#repeat-a-sql-statement) below.
 
@@ -172,6 +172,17 @@ The **Version** and **Cluster ID** details are particularly noteworthy:
 
 {% include {{ page.version.version }}/sql/sql-errors.md %}
 
+## Allow potentially unsafe SQL statements
+
+When running an interactive session, the SQL shell enables only "safe" SQL statements by default. In this state, CockroachDB blocks statements that are likely to cause accidental data loss or unexpected behavior.
+
+To allow potentially unsafe statements:
+
+- Start the shell with [`--safe-updates=false`](#flag-safe-updates), or
+- In a SQL session, run `SET sql_safe_updates = false` to disable the [`sql_safe_updates` session variable]({% link {{ page.version.version }}/set-vars.md %}#sql-safe-updates) before issuing the statement (and re-enable it afterwards if desired).
+
+For details on which statements are disallowed when safe updates are enabled, see the documentation for the [`sql_safe_updates` session variable]({% link {{ page.version.version }}/set-vars.md %}#sql-safe-updates).
+
 ## Examples
 
 {% include {{ page.version.version }}/sql/sql-examples.md %}