v25.4 changes related to allow_unsafe_internals session variable

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`, only allowlisted objects are accessible without internal privileges.<br><br>**Warning**: In future releases, this session variable will default to `off` and then will be removed. To assess potential downstream impacts 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/v25.4/crdb-internal.md

@@ -7,6 +7,30 @@ 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.
 
+## Access control
+
+{% include_cached new-in.html version="v25.4" %} CockroachDB treats most objects in the `crdb_internal` schema, as well as descriptors 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 defaults to `on`, but you can disable access by setting it to `off`:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SET allow_unsafe_internals = off;
+~~~
+
+When set to `off`, external sessions can read only the allowlisted `crdb_internal` objects that are supported for production use (the tables marked ✓ in the table below). All other tables and built-in functions that use the `crdb_internal` namespace require either an internal caller or explicitly enabling `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 %}), depend on internal queries that access otherwise restricted data. These commands are designed to bypass the `allow_unsafe_internals` setting, so they continue to function even when direct access to unsafe internals 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, generating a record of emergency access to system internals.
+
+{{site.data.alerts.callout_danger}}
+In future releases, the `allow_unsafe_internals` session variable will default to `off` and then will be removed. To assess potential downstream impacts 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>
 
 ## Tables

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

@@ -234,7 +234,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.
@@ -246,8 +248,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 %}
@@ -269,6 +269,67 @@ 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 future releases, the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals) will default to `off` and then will be removed. To assess potential downstream impacts 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.
+
+This command enables access to unsafe internals for the user `max`:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+ALTER ROLE max SET allow_unsafe_internals = on;
+~~~
+
+When the user `max` connects to a session and accesses an unsafe internal object, an event is logged:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT count(*) FROM crdb_internal.active_range_feeds;
+~~~
+
+This `unsafe_internals_accessed` event shows that the internal table `crdb_internal.active_range_feeds` was accessed by user `max` 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=‹max›] 23 ={"Timestamp":1759261861128925000,"EventType":"unsafe_internals_accessed","Query":"SELECT count(*) FROM \"\".crdb_internal.active_range_feeds"}
+~~~
+
+This command disables access to unsafe internals for the user `max`:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+ALTER ROLE max SET allow_unsafe_internals = off;
+~~~
+
+When the user `max` connects to a session and tries to access an unsafe internal object, an event is logged:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT count(*) FROM crdb_internal.active_range_feeds;
+~~~
+
+This `unsafe_internals_denied` event shows that access to the internal table `crdb_internal.active_range_feeds` was denied to the user `max`, 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=‹max›] 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 descriptors in the `system` database is gated by the [`allow_unsafe_internals` session variable]({% link {{ page.version.version }}/session-variables.md %}#allow-unsafe-internals). For details, see [`crdb_internal` access control]({% link {{ page.version.version }}/crdb-internal.md %}#access-control).
+
+{{site.data.alerts.callout_danger}}
+In future releases, the `allow_unsafe_internals` session variable will default to `off` and then will be removed. To assess potential downstream impacts 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}}