From 21534b6e4f32d9220e6abbaadc1263daf698240a Mon Sep 17 00:00:00 2001 From: Florence Morris Date: Fri, 3 Oct 2025 11:48:41 -0400 Subject: [PATCH 1/8] 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, modified by codex. --- .../_includes/v25.4/misc/session-vars.md | 1 + src/current/v25.4/crdb-internal.md | 15 +++++ src/current/v25.4/functions-and-operators.md | 2 +- src/current/v25.4/logging-use-cases.md | 63 ++++++++++++++++++- src/current/v25.4/system-catalogs.md | 2 + 5 files changed, 79 insertions(+), 4 deletions(-) diff --git a/src/current/_includes/v25.4/misc/session-vars.md b/src/current/_includes/v25.4/misc/session-vars.md index faa02c08700..d429bd31a91 100644 --- a/src/current/_includes/v25.4/misc/session-vars.md +++ b/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 %})? | |---|---|---|---|---| | `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 | +| New in v25.4: `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. | `on` | 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 %}#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 | diff --git a/src/current/v25.4/crdb-internal.md b/src/current/v25.4/crdb-internal.md index 248d37d0931..92073565fd5 100644 --- a/src/current/v25.4/crdb-internal.md +++ b/src/current/v25.4/crdb-internal.md @@ -7,6 +7,21 @@ 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`. + +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. + ## Tables diff --git a/src/current/v25.4/functions-and-operators.md b/src/current/v25.4/functions-and-operators.md index 550ba99eb0a..fd28c6a6df7 100644 --- a/src/current/v25.4/functions-and-operators.md +++ b/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) diff --git a/src/current/v25.4/logging-use-cases.md b/src/current/v25.4/logging-use-cases.md index 17addd64f40..0ee35f2bb10 100644 --- a/src/current/v25.4/logging-use-cases.md +++ b/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,63 @@ 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 + +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 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 %}). diff --git a/src/current/v25.4/system-catalogs.md b/src/current/v25.4/system-catalogs.md index e3767873767..2022655eeb5 100644 --- a/src/current/v25.4/system-catalogs.md +++ b/src/current/v25.4/system-catalogs.md @@ -14,6 +14,8 @@ 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. +Access to the `crdb_internal` schema and many 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}} 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}} From 637490323b33eb72f0ede42a3d8ceea6511126d1 Mon Sep 17 00:00:00 2001 From: Florence Morris Date: Mon, 6 Oct 2025 13:40:56 -0400 Subject: [PATCH 2/8] In system-catalogs.md, added description of allow_unsafe_internals with a warning. --- src/current/_includes/v25.4/misc/session-vars.md | 2 +- src/current/v25.4/crdb-internal.md | 11 ++++++++++- src/current/v25.4/logging-use-cases.md | 6 +++++- src/current/v25.4/system-catalogs.md | 6 +++++- 4 files changed, 21 insertions(+), 4 deletions(-) diff --git a/src/current/_includes/v25.4/misc/session-vars.md b/src/current/_includes/v25.4/misc/session-vars.md index d429bd31a91..d45475ccdd1 100644 --- a/src/current/_includes/v25.4/misc/session-vars.md +++ b/src/current/_includes/v25.4/misc/session-vars.md @@ -1,7 +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 %})? | |---|---|---|---|---| | `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 | -| New in v25.4: `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. | `on` | Yes | Yes | +| New in v25.4: `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.

**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 | | `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 %}#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 | diff --git a/src/current/v25.4/crdb-internal.md b/src/current/v25.4/crdb-internal.md index 92073565fd5..198aea36e9b 100644 --- a/src/current/v25.4/crdb-internal.md +++ b/src/current/v25.4/crdb-internal.md @@ -9,7 +9,12 @@ The `crdb_internal` [system catalog]({% link {{ page.version.version }}/system-c ## 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 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: @@ -22,6 +27,10 @@ Some SHOW commands, such as [SHOW DATABASES]({% link {{ page.version.version }}/ 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}} + ## Tables diff --git a/src/current/v25.4/logging-use-cases.md b/src/current/v25.4/logging-use-cases.md index 0ee35f2bb10..345d838de56 100644 --- a/src/current/v25.4/logging-use-cases.md +++ b/src/current/v25.4/logging-use-cases.md @@ -271,9 +271,13 @@ All possible `SENSITIVE_ACCESS` event types are detailed in the [reference docum #### 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 is enabled: +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` diff --git a/src/current/v25.4/system-catalogs.md b/src/current/v25.4/system-catalogs.md index 2022655eeb5..b6651c1a6eb 100644 --- a/src/current/v25.4/system-catalogs.md +++ b/src/current/v25.4/system-catalogs.md @@ -14,7 +14,11 @@ 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. -Access to the `crdb_internal` schema and many 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). +{% 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 %}). From 6fc6f27ee68a8050d3e11de0e9dfc3144ac94458 Mon Sep 17 00:00:00 2001 From: Florence Morris Date: Fri, 17 Oct 2025 14:07:00 -0400 Subject: [PATCH 3/8] =?UTF-8?q?Incorporated=20Brian=E2=80=99s=20feedback.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../_includes/v25.4/misc/session-vars.md | 2 +- src/current/v25.4/crdb-internal.md | 8 ++++---- src/current/v25.4/logging-use-cases.md | 20 +++++++++---------- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/src/current/_includes/v25.4/misc/session-vars.md b/src/current/_includes/v25.4/misc/session-vars.md index d45475ccdd1..a2f852af662 100644 --- a/src/current/_includes/v25.4/misc/session-vars.md +++ b/src/current/_includes/v25.4/misc/session-vars.md @@ -1,7 +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 %})? | |---|---|---|---|---| | `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 | -| New in v25.4: `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.

**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 | +| New in v25.4: `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.

**Warning**: In a future release, this session variable will default to `off`. To assess potential downstream impacts on your setup, set `allow_unsafe_internals` to `off` in a non-production environment. | `on` | 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 %}#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 | diff --git a/src/current/v25.4/crdb-internal.md b/src/current/v25.4/crdb-internal.md index 198aea36e9b..0acc196667f 100644 --- a/src/current/v25.4/crdb-internal.md +++ b/src/current/v25.4/crdb-internal.md @@ -9,26 +9,26 @@ The `crdb_internal` [system catalog]({% link {{ page.version.version }}/system-c ## 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 new-in.html version="v25.4" %} CockroachDB treats most objects in the `crdb_internal` schema and 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: +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 you to 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 %}), 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. +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, 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. +In a future release, the `allow_unsafe_internals` session variable will default to `off`. To assess potential downstream impacts on your setup, set `allow_unsafe_internals` to `off` in a non-production environment. {{site.data.alerts.end}} diff --git a/src/current/v25.4/logging-use-cases.md b/src/current/v25.4/logging-use-cases.md index 345d838de56..d52b39882e5 100644 --- a/src/current/v25.4/logging-use-cases.md +++ b/src/current/v25.4/logging-use-cases.md @@ -284,44 +284,44 @@ The following events may be logged to the `SENSITIVE_ACCESS` channel, depending These events record both successful and denied attempts to access internal system objects. -This command enables access to unsafe internals for the user `max`: +This command enables access to unsafe internals for the user `allow_unsafe_internals_on`: {% include_cached copy-clipboard.html %} ~~~ sql -ALTER ROLE max SET allow_unsafe_internals = on; +ALTER ROLE allow_unsafe_internals_on SET allow_unsafe_internals = on; ~~~ -When the user `max` connects to a session and accesses an unsafe internal object, an event is logged: +When the user `allow_unsafe_internals_on` 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: +This `unsafe_internals_accessed` event shows that the internal table `crdb_internal.active_range_feeds` was accessed by user `allow_unsafe_internals_on` 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"} +W250930 19:51:01.128927 464484 8@util/log/event_log.go:90 ⋮ [T1,Vsystem,n1,client=127.0.0.1:65020,hostssl,user=‹allow_unsafe_internals_on›] 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`: +This command disables access to unsafe internals for the user `allow_unsafe_internals_off`: {% include_cached copy-clipboard.html %} ~~~ sql -ALTER ROLE max SET allow_unsafe_internals = off; +ALTER ROLE allow_unsafe_internals_off 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: +When the user `allow_unsafe_internals_off` 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: +This `unsafe_internals_denied` event shows that access to the internal table `crdb_internal.active_range_feeds` was denied to the user `allow_unsafe_internals_off`, 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"} +W250930 15:47:06.906181 122782 8@util/log/event_log.go:90 ⋮ [T1,Vsystem,n1,client=127.0.0.1:57104,hostssl,user=‹allow_unsafe_internals_off›] 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. From 6ec71f881edd5fe6b47a2a54973427acdc32f2a4 Mon Sep 17 00:00:00 2001 From: Florence Morris Date: Tue, 21 Oct 2025 14:46:26 -0400 Subject: [PATCH 4/8] =?UTF-8?q?Incorporated=20Kevin=E2=80=99s=20feedback.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../_includes/v25.4/misc/session-vars.md | 2 +- .../lease-preference-system-database.md | 4 ++++ src/current/v25.4/crdb-internal.md | 8 ++++---- src/current/v25.4/logging-use-cases.md | 18 +++++++++++++----- src/current/v25.4/system-catalogs.md | 4 ++-- 5 files changed, 24 insertions(+), 12 deletions(-) diff --git a/src/current/_includes/v25.4/misc/session-vars.md b/src/current/_includes/v25.4/misc/session-vars.md index a2f852af662..6321dd5905b 100644 --- a/src/current/_includes/v25.4/misc/session-vars.md +++ b/src/current/_includes/v25.4/misc/session-vars.md @@ -1,7 +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 %})? | |---|---|---|---|---| | `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 | -| New in v25.4: `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.

**Warning**: In a future release, this session variable will default to `off`. To assess potential downstream impacts on your setup, set `allow_unsafe_internals` to `off` in a non-production environment. | `on` | Yes | Yes | +| New in v25.4: `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 %}).

**Warning**: In a future 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 | | `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 %}#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 | diff --git a/src/current/_includes/v25.4/performance/lease-preference-system-database.md b/src/current/_includes/v25.4/performance/lease-preference-system-database.md index 9661aef0e2d..257078b9d5c 100644 --- a/src/current/_includes/v25.4/performance/lease-preference-system-database.md +++ b/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). However, the above `ALTER DATABASE system` statement functions regardless of the variable's setting because it does not access tables or 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. diff --git a/src/current/v25.4/crdb-internal.md b/src/current/v25.4/crdb-internal.md index 0acc196667f..4f4e2942f2c 100644 --- a/src/current/v25.4/crdb-internal.md +++ b/src/current/v25.4/crdb-internal.md @@ -9,14 +9,14 @@ The `crdb_internal` [system catalog]({% link {{ page.version.version }}/system-c ## Access control -{% include_cached new-in.html version="v25.4" %} CockroachDB treats most objects in the `crdb_internal` schema and 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 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`, but you should set it to `off` to avoid unintentional access unless explicitly advised by Cockroach Labs. {% 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 you to explicitly enable `allow_unsafe_internals` for the session. +When `allow_unsafe_internals` is set to `off`, you should access only [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}). Additionally, external sessions can read the 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 @@ -25,10 +25,10 @@ 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, generating a record of emergency access to system internals. +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 release, the `allow_unsafe_internals` session variable will default to `off`. To assess potential downstream impacts on your setup, set `allow_unsafe_internals` to `off` in a non-production environment. +In a future release, the `allow_unsafe_internals` 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. {{site.data.alerts.end}} diff --git a/src/current/v25.4/logging-use-cases.md b/src/current/v25.4/logging-use-cases.md index d52b39882e5..5d0ab5b1e34 100644 --- a/src/current/v25.4/logging-use-cases.md +++ b/src/current/v25.4/logging-use-cases.md @@ -272,7 +272,7 @@ All possible `SENSITIVE_ACCESS` event types are detailed in the [reference docum #### 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. +In a future 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. @@ -284,6 +284,8 @@ The following events may be logged to the `SENSITIVE_ACCESS` channel, depending 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 `allow_unsafe_internals_on`: {% include_cached copy-clipboard.html %} @@ -291,19 +293,25 @@ This command enables access to unsafe internals for the user `allow_unsafe_inter ALTER ROLE allow_unsafe_internals_on SET allow_unsafe_internals = on; ~~~ -When the user `allow_unsafe_internals_on` connects to a session and accesses an unsafe internal object, an event is logged: +When the user `allow_unsafe_internals_on` 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 shows that the internal table `crdb_internal.active_range_feeds` was accessed by user `allow_unsafe_internals_on` who issued a [`SELECT`]({% link {{ page.version.version }}/selection-queries.md %}) statement: +This `unsafe_internals_accessed` event indicates that the internal table `crdb_internal.active_range_feeds` was accessed by user `allow_unsafe_internals_on`, 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=‹allow_unsafe_internals_on›] 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 indentify 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 `allow_unsafe_internals_off`: {% include_cached copy-clipboard.html %} @@ -311,14 +319,14 @@ This command disables access to unsafe internals for the user `allow_unsafe_inte ALTER ROLE allow_unsafe_internals_off SET allow_unsafe_internals = off; ~~~ -When the user `allow_unsafe_internals_off` connects to a session and tries to access an unsafe internal object, an event is logged: +When the user `allow_unsafe_internals_off` 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 shows that access to the internal table `crdb_internal.active_range_feeds` was denied to the user `allow_unsafe_internals_off`, who issued a [`SELECT`]({% link {{ page.version.version }}/selection-queries.md %}) statement: +This `unsafe_internals_denied` event indicates that access to the internal table `crdb_internal.active_range_feeds` was denied for the user `allow_unsafe_internals_off`, 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=‹allow_unsafe_internals_off›] 18 ={"Timestamp":1759247226906172000,"EventType":"unsafe_internals_denied","Query":"SELECT count(*) FROM \"\".crdb_internal.active_range_feeds"} diff --git a/src/current/v25.4/system-catalogs.md b/src/current/v25.4/system-catalogs.md index b6651c1a6eb..9cb2252f5cd 100644 --- a/src/current/v25.4/system-catalogs.md +++ b/src/current/v25.4/system-catalogs.md @@ -14,10 +14,10 @@ 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). +{% 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 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. +In a future release, the `allow_unsafe_internals` 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. {{site.data.alerts.end}} {{site.data.alerts.callout_danger}} From d2dfc37ae86e4d80e191f145a41a4e485738723c Mon Sep 17 00:00:00 2001 From: Florence Morris Date: Tue, 21 Oct 2025 16:33:25 -0400 Subject: [PATCH 5/8] Clarified sentence. --- .../v25.4/performance/lease-preference-system-database.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/current/_includes/v25.4/performance/lease-preference-system-database.md b/src/current/_includes/v25.4/performance/lease-preference-system-database.md index 257078b9d5c..fcb9aadc47e 100644 --- a/src/current/_includes/v25.4/performance/lease-preference-system-database.md +++ b/src/current/_includes/v25.4/performance/lease-preference-system-database.md @@ -6,7 +6,7 @@ ALTER DATABASE system CONFIGURE ZONE USING constraints = '{"+region=us-east1": 1 ~~~ {{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). However, the above `ALTER DATABASE system` statement functions regardless of the variable's setting because it does not access tables or built-in functions. +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). However, 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. From d12c358b3f5b3b606199c86df1e21cf8c2e605d5 Mon Sep 17 00:00:00 2001 From: Florence Morris Date: Fri, 24 Oct 2025 17:30:46 -0400 Subject: [PATCH 6/8] Added note to work with account team or support. --- src/current/v25.4/crdb-internal.md | 14 ++++++++++---- src/current/v25.4/system-catalogs.md | 2 +- 2 files changed, 11 insertions(+), 5 deletions(-) diff --git a/src/current/v25.4/crdb-internal.md b/src/current/v25.4/crdb-internal.md index fe6d5a46bdc..0db07431dfe 100644 --- a/src/current/v25.4/crdb-internal.md +++ b/src/current/v25.4/crdb-internal.md @@ -5,18 +5,24 @@ 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`, but you should set it to `off` to avoid unintentional access unless explicitly advised by Cockroach Labs. +{% 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; ~~~ -When `allow_unsafe_internals` is set to `off`, you should access only [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}). Additionally, external sessions can read the 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. +With `allow_unsafe_internals` set to `off`, access only [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}). + +{{site.data.alerts.callout_info}} +If you need information that is not available through production-supported [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}), work with 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 @@ -28,7 +34,7 @@ Some `SHOW commands`, such as [`SHOW DATABASES`]({% link {{ page.version.version 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 release, the `allow_unsafe_internals` 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. +In a future 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}} diff --git a/src/current/v25.4/system-catalogs.md b/src/current/v25.4/system-catalogs.md index 9cb2252f5cd..ee7b9d01643 100644 --- a/src/current/v25.4/system-catalogs.md +++ b/src/current/v25.4/system-catalogs.md @@ -17,7 +17,7 @@ The following system catalogs are available as schemas preloaded to every databa {% 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 release, the `allow_unsafe_internals` 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. +In a future 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}} From 6ec7c8c804490142329c39bdc2e3cbb0caf6bf0c Mon Sep 17 00:00:00 2001 From: Florence Morris Date: Tue, 28 Oct 2025 12:16:46 -0400 Subject: [PATCH 7/8] =?UTF-8?q?Incorporated=20Peach=E2=80=99s=20feedback.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../lease-preference-system-database.md | 2 +- src/current/v25.4/crdb-internal.md | 6 ++--- src/current/v25.4/logging-use-cases.md | 22 +++++++++---------- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/src/current/_includes/v25.4/performance/lease-preference-system-database.md b/src/current/_includes/v25.4/performance/lease-preference-system-database.md index fcb9aadc47e..383270efcae 100644 --- a/src/current/_includes/v25.4/performance/lease-preference-system-database.md +++ b/src/current/_includes/v25.4/performance/lease-preference-system-database.md @@ -6,7 +6,7 @@ ALTER DATABASE system CONFIGURE ZONE USING constraints = '{"+region=us-east1": 1 ~~~ {{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). However, the above `ALTER DATABASE system` statement executes regardless of the variable's setting because it does not access tables or invoke built-in functions. +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. diff --git a/src/current/v25.4/crdb-internal.md b/src/current/v25.4/crdb-internal.md index 0db07431dfe..e97e16f5e9d 100644 --- a/src/current/v25.4/crdb-internal.md +++ b/src/current/v25.4/crdb-internal.md @@ -16,10 +16,10 @@ The `crdb_internal` [system catalog]({% link {{ page.version.version }}/system-c SET allow_unsafe_internals = off; ~~~ -With `allow_unsafe_internals` set to `off`, access only [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}). +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 that is not available through production-supported [`information_schema` tables]({% link {{ page.version.version }}/information-schema.md %}), work with your account team or contact [Cockroach Labs support](https://support.cockroachlabs.com). +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. @@ -31,7 +31,7 @@ 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. +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 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. diff --git a/src/current/v25.4/logging-use-cases.md b/src/current/v25.4/logging-use-cases.md index 5d0ab5b1e34..dca87b3eb12 100644 --- a/src/current/v25.4/logging-use-cases.md +++ b/src/current/v25.4/logging-use-cases.md @@ -286,50 +286,50 @@ These events record both successful and denied attempts to access internal syste ##### Unsafe internals enabled -This command enables access to unsafe internals for the user `allow_unsafe_internals_on`: +This command enables access to unsafe internals for the user `can_access_unsafe_internals`: {% include_cached copy-clipboard.html %} ~~~ sql -ALTER ROLE allow_unsafe_internals_on SET allow_unsafe_internals = on; +ALTER ROLE can_access_unsafe_internals SET allow_unsafe_internals = on; ~~~ -When the user `allow_unsafe_internals_on` connects to a session and accesses an unsafe internal object, the event is logged: +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 `allow_unsafe_internals_on`, who issued a [`SELECT`]({% link {{ page.version.version }}/selection-queries.md %}) statement: +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=‹allow_unsafe_internals_on›] 23 ={"Timestamp":1759261861128925000,"EventType":"unsafe_internals_accessed","Query":"SELECT count(*) FROM \"\".crdb_internal.active_range_feeds"} +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 indentify which tools or scripts attempted to access these internals. +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 `allow_unsafe_internals_off`: +This command disables access to unsafe internals for the user `can_not_access_unsafe_internals`: {% include_cached copy-clipboard.html %} ~~~ sql -ALTER ROLE allow_unsafe_internals_off SET allow_unsafe_internals = off; +ALTER ROLE can_not_access_unsafe_internals SET allow_unsafe_internals = off; ~~~ -When the user `allow_unsafe_internals_off` connects to a session and attempts to access an unsafe internal object, the event is logged: +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 `allow_unsafe_internals_off`, who issued a [`SELECT`]({% link {{ page.version.version }}/selection-queries.md %}) statement: +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=‹allow_unsafe_internals_off›] 18 ={"Timestamp":1759247226906172000,"EventType":"unsafe_internals_denied","Query":"SELECT count(*) FROM \"\".crdb_internal.active_range_feeds"} +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. From e3290e13c52b5e4b15c5fa2dabc1ae0bc233e5e9 Mon Sep 17 00:00:00 2001 From: Florence Morris Date: Fri, 31 Oct 2025 16:42:20 -0400 Subject: [PATCH 8/8] Replaced future release with future major release. --- src/current/_includes/v25.4/misc/session-vars.md | 2 +- src/current/v25.4/crdb-internal.md | 2 +- src/current/v25.4/logging-use-cases.md | 2 +- src/current/v25.4/system-catalogs.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/src/current/_includes/v25.4/misc/session-vars.md b/src/current/_includes/v25.4/misc/session-vars.md index 6321dd5905b..716bdc1af33 100644 --- a/src/current/_includes/v25.4/misc/session-vars.md +++ b/src/current/_includes/v25.4/misc/session-vars.md @@ -1,7 +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 %})? | |---|---|---|---|---| | `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 | -| New in v25.4: `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 %}).

**Warning**: In a future 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 | +| New in v25.4: `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 %}).

**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 | | `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 %}#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 | diff --git a/src/current/v25.4/crdb-internal.md b/src/current/v25.4/crdb-internal.md index 864758d2507..21362279cc1 100644 --- a/src/current/v25.4/crdb-internal.md +++ b/src/current/v25.4/crdb-internal.md @@ -34,7 +34,7 @@ Some `SHOW commands`, such as [`SHOW DATABASES`]({% link {{ page.version.version 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 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. +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}} diff --git a/src/current/v25.4/logging-use-cases.md b/src/current/v25.4/logging-use-cases.md index dca87b3eb12..ee9fd6ddd9b 100644 --- a/src/current/v25.4/logging-use-cases.md +++ b/src/current/v25.4/logging-use-cases.md @@ -272,7 +272,7 @@ All possible `SENSITIVE_ACCESS` event types are detailed in the [reference docum #### Example: Unsafe internals {{site.data.alerts.callout_danger}} -In a future 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. +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. diff --git a/src/current/v25.4/system-catalogs.md b/src/current/v25.4/system-catalogs.md index ee7b9d01643..5e042ff6fd1 100644 --- a/src/current/v25.4/system-catalogs.md +++ b/src/current/v25.4/system-catalogs.md @@ -17,7 +17,7 @@ The following system catalogs are available as schemas preloaded to every databa {% 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 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. +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}}