v25.4 changes related to allow_unsafe_internals session variable (#20486)

- In session-vars.md, added row for allow_unsafe_internals.
- In crdb-internal.md, added a section for Access control.
- In functions-and-operators.md, removed reference to a crdb_internal built-in function.
- In logging-use-cases, added a section for Example: Unsafe internals.
- In system-catalogs.md, added description of allow_unsafe_internals with a warning.
- In lease-preference-system-database.md, added clarification note.

* Incorporated Brian’s feedback.

* Incorporated Kevin’s feedback.

* Incorporated Peach’s feedback.

Author: florence-crl

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

@@ -1,6 +1,7 @@
 | Variable name | Description | Initial value | Modify with [`SET`]({% link {{ page.version.version }}/set-vars.md %})? | View with [`SHOW`]({% link {{ page.version.version }}/show-vars.md %})? |
 |---|---|---|---|---|
 | <a id="always-distribute-full-scans"></a> `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 |
+| <a id="allow-unsafe-internals"></a><span class="version-tag">New in v25.4:</span> `allow_unsafe_internals` | Controls access to unsafe internals in the `system` database and the [`crdb_internal`]({% link {{ page.version.version }}/crdb-internal.md %}#access-control) schema. When set to `off`, you should access only [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}).<br><br>**Warning**: In a future major release, this session variable will default to `off`. To [assess potential downstream impacts]({% link {{ page.version.version }}/logging-use-cases.md %}#unsafe-internals-disabled) on your setup, set `allow_unsafe_internals` to `off` in a non-production environment. | `on` | Yes | Yes |
 | <a id="application-name"></a> `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 |
 | <a id="autocommit-before-ddl"></a> `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 |
 | <a id="bytea-output"></a> `bytea_output` | The [mode for conversions from `STRING` to `BYTES`]({% link {{ page.version.version }}/bytes.md %}#supported-conversions). | hex | Yes | Yes |

src/current/_includes/v25.4/performance/lease-preference-system-database.md

@@ -5,6 +5,10 @@ To reduce latency while making {% if page.name == "online-schema-changes.md" %}o
 ALTER DATABASE system CONFIGURE ZONE USING constraints = '{"+region=us-east1": 1}', lease_preferences = '[[+region=us-east1]]';
 ~~~
 
+{{site.data.alerts.callout_info}}
+Access to tables and built-in functions in the `system` database is controlled by the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals). The above `ALTER DATABASE system` statement executes regardless of the variable's setting because it does not access tables or invoke built-in functions.
+{{site.data.alerts.end}}
+
 Run all subsequent schema changes from a node in the specified region.
 
 If you do not intend to run more schema changes from that region, you can safely [remove the lease preference from the zone configuration]({% link {{ page.version.version }}/alter-database.md %}#remove-a-replication-zone) for the system database.

src/current/v25.4/crdb-internal.md

@@ -5,7 +5,37 @@ toc: true
 docs_area: reference.sql
 ---
 
-The `crdb_internal` [system catalog]({% link {{ page.version.version }}/system-catalogs.md %}) is a [schema]({% link {{ page.version.version }}/schema-design-overview.md %}#schemas) that contains information about internal objects, processes, and metrics related to a specific database. `crdb_internal` tables are read-only.
+The `crdb_internal` [system catalog]({% link {{ page.version.version }}/system-catalogs.md %}) is a [schema]({% link {{ page.version.version }}/schema-design-overview.md %}#schemas) that contains information about internal objects, processes, and metrics related to a specific database. `crdb_internal` tables are read-only.  The `crdb_internal` schema is intended for advanced support scenarios only, and should be accessed under the guidance of Cockroach Labs.
+
+## Access control
+
+{% include_cached new-in.html version="v25.4" %} CockroachDB treats most objects in the `crdb_internal` schema, as well as tables and built-in functions in the `system` database, as *unsafe internals*. Access to these objects is controlled by the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals). This variable defaults to `on`. Set it to `off` to prevent unintentional access unless explicitly advised by Cockroach Labs.
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SET allow_unsafe_internals = off;
+~~~
+
+With `allow_unsafe_internals` set to `off`, you should access only [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}).
+
+{{site.data.alerts.callout_info}}
+If you need information not available through production-supported [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}), contact your account team or contact [Cockroach Labs support](https://support.cockroachlabs.com).
+{{site.data.alerts.end}}
+
+When `allow_unsafe_internals` is set to `off`, external sessions can still read allowlisted `crdb_internal` objects that are supported for production use (those marked ✓ in the table below). To access all other tables and built-in functions in `crdb_internal` and `system`, you must explicitly enable `allow_unsafe_internals` for the session.
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SET allow_unsafe_internals = on;
+~~~
+
+Some `SHOW commands`, such as [`SHOW DATABASES`]({% link {{ page.version.version }}/show-databases.md %}), and CockroachDB tools, such as the [DB Console]({% link {{ page.version.version }}/ui-overview.md %}) and [`cockroach debug zip`]({% link {{ page.version.version }}/cockroach-debug-zip.md %}), rely on internal queries that access restricted data. These commands and tools are designed to bypass the `allow_unsafe_internals` setting and continue to function even when direct access is disabled.
+
+CockroachDB emits log events to the [`SENSITIVE_ACCESS` channel]({% link {{ page.version.version }}/logging-use-cases.md %}#example-unsafe-internals) when a user overrides or is denied access to unsafe internals, creating a record of emergency access to system internals. Monitor these logs to ensure that neither workloads nor you and your users are unintentionally accessing unsafe internals.
+
+{{site.data.alerts.callout_danger}}
+In a future major release, the `allow_unsafe_internals` session variable will default to `off`. To prepare for this change and [assess potential downstream impacts]({% link {{ page.version.version }}/logging-use-cases.md %}#unsafe-internals-disabled) on your setup, set `allow_unsafe_internals` to `off` in a non-production environment.
+{{site.data.alerts.end}}
 
 <a id="data-exposed-by-crdb_internal"></a>
 

src/current/v25.4/functions-and-operators.md

@@ -23,7 +23,7 @@ A function's _volatility_ is a promise to the [optimizer]({% link {{ page.versio
 
 Type   | Description | Examples
 -------|-------------|----------
-Volatile | The function can modify the state of the database and is not guaranteed to return the same results given the same arguments in any context. | `random`, `crdb_internal.force_error`, `nextval`, `now`
+Volatile | The function can modify the state of the database and is not guaranteed to return the same results given the same arguments in any context. | `random`, `nextval`, `now`
 Stable | The function is guaranteed to return the same results given the same arguments whenever it is evaluated within the same statement. The optimizer can optimize multiple calls of the function to a single call. | `current_timestamp`, `current_date`
 Immutable | The function does not depend on configuration settings and is guaranteed to return the same results given the same arguments in any context.  The optimizer can pre-evaluate the function when a query calls it with constant arguments. | `log`, `from_json`
 Leakproof | The function does not depend on configuration settings and is guaranteed to return the same results given the same arguments in any context. In addition, no information about the arguments is conveyed except via the return value. Any function that might throw an error depending on the values of its arguments is not leakproof. Leakproof is strictly stronger than Immutable. | Integer [comparison](#comparison-functions)

src/current/v25.4/logging-use-cases.md

@@ -240,7 +240,9 @@ All possible `SESSIONS` event types are detailed in the [reference documentation
 
 ### SENSITIVE_ACCESS
 
-The [`SENSITIVE_ACCESS`]({% link {{ page.version.version }}/logging.md %}#sensitive_access) channel logs SQL audit events. These include all queries being run against [audited tables]({% link {{ page.version.version }}/alter-table.md %}#experimental_audit), when enabled, as well as queries executed by users with the [`admin`]({% link {{ page.version.version }}/security-reference/authorization.md %}#admin-role) role.
+The [`SENSITIVE_ACCESS`]({% link {{ page.version.version }}/logging.md %}#sensitive_access) channel logs SQL audit events. These include all queries run against [audited tables]({% link {{ page.version.version }}/alter-table.md %}#experimental_audit), when enabled, and queries executed by users with the [`admin`]({% link {{ page.version.version }}/security-reference/authorization.md %}#admin-role) role. It also logs when a user overrides or is denied access by the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/crdb-internal.md %}#access-control), generating a record of emergency access to system internals.
+
+#### Example: Audit events
 
 {{site.data.alerts.callout_info}}
 Enabling these logs can negatively impact performance. We recommend using `SENSITIVE_ACCESS` for security purposes only.
@@ -252,8 +254,6 @@ Enabling these logs can negatively impact performance. We recommend using `SENSI
 
 To log all queries against a specific table, enable auditing on the table with [`ALTER TABLE ... EXPERIMENTAL_AUDIT`]({% link {{ page.version.version }}/alter-table.md %}#experimental_audit).
 
-#### Example: Audit events
-
 This command enables auditing on a `customers` table:
 
 {% include_cached copy-clipboard.html %}
@@ -275,6 +275,75 @@ I210323 18:50:04.518707 1182 8@util/log/event_log.go:32 ⋮ [n1,client=‹[::1]:
 All possible `SENSITIVE_ACCESS` event types are detailed in the [reference documentation]({% link {{ page.version.version }}/eventlog.md %}#sql-access-audit-events). For a detailed tutorial on table auditing, see [SQL Audit Logging]({% link {{ page.version.version }}/sql-audit-logging.md %}).
 {{site.data.alerts.end}}
 
+#### Example: Unsafe internals
+
+{{site.data.alerts.callout_danger}}
+In a future major release, the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals) will default to `off`. To [assess potential downstream impacts](#unsafe-internals-disabled) on your setup, set `allow_unsafe_internals` to `off` in a non-production environment.
+{{site.data.alerts.end}}
+
+CockroachDB emits log events to the `SENSITIVE_ACCESS` channel when a user overrides or is denied access to [unsafe internals]({% link {{ page.version.version }}/crdb-internal.md %}#access-control), creating a log of emergency access to system internals.
+
+The following events may be logged to the `SENSITIVE_ACCESS` channel, depending on whether the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals) is enabled:
+
+- `unsafe_internals_accessed`
+- `unsafe_internals_denied`
+
+These events record both successful and denied attempts to access internal system objects.
+
+##### Unsafe internals enabled
+
+This command enables access to unsafe internals for the user `can_access_unsafe_internals`:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+ALTER ROLE can_access_unsafe_internals SET allow_unsafe_internals = on;
+~~~
+
+When the user `can_access_unsafe_internals` connects to a session and accesses an unsafe internal object, the event is logged:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT count(*) FROM crdb_internal.active_range_feeds;
+~~~
+
+This `unsafe_internals_accessed` event indicates that the internal table `crdb_internal.active_range_feeds` was accessed by user `can_access_unsafe_internals`, who issued a [`SELECT`]({% link {{ page.version.version }}/selection-queries.md %}) statement:
+
+~~~
+W250930 19:51:01.128927 464484 8@util/log/event_log.go:90 ⋮ [T1,Vsystem,n1,client=127.0.0.1:65020,hostssl,user=‹can_access_unsafe_internals›] 23 ={"Timestamp":1759261861128925000,"EventType":"unsafe_internals_accessed","Query":"SELECT count(*) FROM \"\".crdb_internal.active_range_feeds"}
+~~~
+
+##### Unsafe internals disabled
+
+To assess potential downstream impacts, disable `allow_unsafe_internals` in a test or staging environment. Monitoring tools or scripts that rely on these internals may be affected. `unsafe_internals_denied` events identify which tools or scripts attempted to access these internals.
+
+This example shows how to identify users denied access to unsafe internal tables.
+
+This command disables access to unsafe internals for the user `can_not_access_unsafe_internals`:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+ALTER ROLE can_not_access_unsafe_internals SET allow_unsafe_internals = off;
+~~~
+
+When the user `can_not_access_unsafe_internals` connects to a session and attempts to access an unsafe internal object, the event is logged:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT count(*) FROM crdb_internal.active_range_feeds;
+~~~
+
+This `unsafe_internals_denied` event indicates that access to the internal table `crdb_internal.active_range_feeds` was denied for the user `can_not_access_unsafe_internals`, who issued a [`SELECT`]({% link {{ page.version.version }}/selection-queries.md %}) statement:
+
+~~~
+W250930 15:47:06.906181 122782 8@util/log/event_log.go:90 ⋮ [T1,Vsystem,n1,client=127.0.0.1:57104,hostssl,user=‹can_not_access_unsafe_internals›] 18 ={"Timestamp":1759247226906172000,"EventType":"unsafe_internals_denied","Query":"SELECT count(*) FROM \"\".crdb_internal.active_range_feeds"}
+~~~
+
+- Preceding the `=` character is the `crdb-v2` event metadata. See the [reference documentation]({% link {{ page.version.version }}/log-formats.md %}#format-crdb-v2) for details on the fields.
+
+{{site.data.alerts.callout_info}}
+All possible `SENSITIVE_ACCESS` event types are detailed in the [reference documentation]({% link {{ page.version.version }}/eventlog.md %}#sql-access-audit-events).
+{{site.data.alerts.end}}
+
 ### PRIVILEGES
 
 The [`PRIVILEGES`]({% link {{ page.version.version }}/logging.md %}#privileges) channel logs SQL privilege changes. These include DDL operations performed by SQL operations that [modify the privileges]({% link {{ page.version.version }}/security-reference/authorization.md %}#managing-privileges) granted to [roles and users]({% link {{ page.version.version }}/security-reference/authorization.md %}#users-and-roles) on databases, schemas, tables, and [user-defined types]({% link {{ page.version.version }}/enum.md %}).

src/current/v25.4/system-catalogs.md

@@ -14,6 +14,12 @@ The following system catalogs are available as schemas preloaded to every databa
 - [`pg_catalog`]({% link {{ page.version.version }}/pg-catalog.md %}),  a schema provided for compatibility with PostgreSQL.
 - [`pg_extension`]({% link {{ page.version.version }}/pg-extension.md %}), a schema catalog with information about CockroachDB extensions.
 
+{% include_cached new-in.html version="v25.4" %} Access to the `crdb_internal` schema and to tables and built-in functions in the `system` database is controlled by the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals). For more information, see [`crdb_internal` access control]({% link {{ page.version.version }}/crdb-internal.md %}#access-control). The `system` and `crdb_internal` schemas are intended for advanced support scenarios only, and should be accessed under the guidance of Cockroach Labs.
+
+{{site.data.alerts.callout_danger}}
+In a future major release, the `allow_unsafe_internals` session variable will default to `off`. To prepare for this change and [assess potential downstream impacts]({% link {{ page.version.version }}/logging-use-cases.md %}#unsafe-internals-disabled) on your setup, set `allow_unsafe_internals` to `off` in a non-production environment.
+{{site.data.alerts.end}}
+
 {{site.data.alerts.callout_danger}}
 Tables in the system catalogs have varying levels of stability. Not all system catalog tables are meant for programmatic purposes. For more information, see [API Support Policy]({% link {{ page.version.version }}/api-support-policy.md %}).
 {{site.data.alerts.end}}