Add docs on session variable precedence order (#20112)

Fixes DOC-7209

NB. These changes are applied to all supported versions v24.1+

Author: rmloveland

src/current/_includes/v24.1/sql/session-variable-precedence-order.md

@@ -0,0 +1,15 @@
+When a [session]({% link {{ page.version.version }}/show-sessions.md %}) starts, CockroachDB determines the initial value of each [session variable]({% link {{ page.version.version }}/session-variables.md %}) by evaluating the settings in the following order (items earlier in the list take precedence over later items):
+
+1. [Connection string parameters]({% link {{ page.version.version }}/connection-parameters.md %}): A value supplied as a query parameter in the connection URL (for example, `.../movr?sslmode=disable&timezone=UTC`).
+1. [Per-role, per-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-role-in-a-specific-database): A value set by `ALTER ROLE {role_name} IN DATABASE {db_name} SET {var}={value}`.
+1. [Per-role, all-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-role): A value set by `ALTER ROLE {role_name} SET {var}={value}`.
+1. [All-role, per-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-specific-database): A value set by `ALTER ROLE ALL IN DATABASE {db_name} SET {var}={value}` or equivalently by `ALTER DATABASE {db_name} SET {var}={value}`.
+1. [Cluster-wide defaults for all roles and all databases]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users): A value set by `ALTER ROLE ALL SET {var}={value}`.
+
+If a session variable is not modified using any of the preceding methods, the built-in system default value is used. Note that the [`root` user]({% link {{ page.version.version }}/security-reference/authorization.md %}#root-user) is exempt from settings 3–5. The `root` user is only affected by values specified in the connection string.
+
+You can also set session variables for the duration of a single transaction by using [`SET LOCAL {var}={value}`]({% link {{ page.version.version }}/set-vars.md %}#set-a-variable-for-the-duration-of-a-single-transaction).
+
+{{site.data.alerts.callout_info}}
+Changes to defaults using the preceding methods only apply to **future** sessions. This is because session variable resolution happens at session start time. To change a default value in an existing open session, set the variable explicitly with [`SET`]({% link {{ page.version.version }}/set-vars.md %}).
+{{site.data.alerts.end}}

src/current/_includes/v24.3/sql/session-variable-precedence-order.md

@@ -0,0 +1,15 @@
+When a [session]({% link {{ page.version.version }}/show-sessions.md %}) starts, CockroachDB determines the initial value of each [session variable]({% link {{ page.version.version }}/session-variables.md %}) by evaluating the settings in the following order (items earlier in the list take precedence over later items):
+
+1. [Connection string parameters]({% link {{ page.version.version }}/connection-parameters.md %}): A value supplied as a query parameter in the connection URL (for example, `.../movr?sslmode=disable&timezone=UTC`).
+1. [Per-role, per-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-role-in-a-specific-database): A value set by `ALTER ROLE {role_name} IN DATABASE {db_name} SET {var}={value}`.
+1. [Per-role, all-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-role): A value set by `ALTER ROLE {role_name} SET {var}={value}`.
+1. [All-role, per-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-specific-database): A value set by `ALTER ROLE ALL IN DATABASE {db_name} SET {var}={value}` or equivalently by `ALTER DATABASE {db_name} SET {var}={value}`.
+1. [Cluster-wide defaults for all roles and all databases]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users): A value set by `ALTER ROLE ALL SET {var}={value}`.
+
+If a session variable is not modified using any of the preceding methods, the built-in system default value is used. Note that the [`root` user]({% link {{ page.version.version }}/security-reference/authorization.md %}#root-user) is exempt from settings 3–5. The `root` user is only affected by values specified in the connection string.
+
+You can also set session variables for the duration of a single transaction by using [`SET LOCAL {var}={value}`]({% link {{ page.version.version }}/set-vars.md %}#set-a-variable-for-the-duration-of-a-single-transaction).
+
+{{site.data.alerts.callout_info}}
+Changes to defaults using the preceding methods only apply to **future** sessions. This is because session variable resolution happens at session start time. To change a default value in an existing open session, set the variable explicitly with [`SET`]({% link {{ page.version.version }}/set-vars.md %}).
+{{site.data.alerts.end}}

src/current/_includes/v25.1/sql/session-variable-precedence-order.md

@@ -0,0 +1,15 @@
+When a [session]({% link {{ page.version.version }}/show-sessions.md %}) starts, CockroachDB determines the initial value of each [session variable]({% link {{ page.version.version }}/session-variables.md %}) by evaluating the settings in the following order (items earlier in the list take precedence over later items):
+
+1. [Connection string parameters]({% link {{ page.version.version }}/connection-parameters.md %}): A value supplied as a query parameter in the connection URL (for example, `.../movr?sslmode=disable&timezone=UTC`).
+1. [Per-role, per-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-role-in-a-specific-database): A value set by `ALTER ROLE {role_name} IN DATABASE {db_name} SET {var}={value}`.
+1. [Per-role, all-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-role): A value set by `ALTER ROLE {role_name} SET {var}={value}`.
+1. [All-role, per-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-specific-database): A value set by `ALTER ROLE ALL IN DATABASE {db_name} SET {var}={value}` or equivalently by `ALTER DATABASE {db_name} SET {var}={value}`.
+1. [Cluster-wide defaults for all roles and all databases]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users): A value set by `ALTER ROLE ALL SET {var}={value}`.
+
+If a session variable is not modified using any of the preceding methods, the built-in system default value is used. Note that the [`root` user]({% link {{ page.version.version }}/security-reference/authorization.md %}#root-user) is exempt from settings 3–5. The `root` user is only affected by values specified in the connection string.
+
+You can also set session variables for the duration of a single transaction by using [`SET LOCAL {var}={value}`]({% link {{ page.version.version }}/set-vars.md %}#set-a-variable-for-the-duration-of-a-single-transaction).
+
+{{site.data.alerts.callout_info}}
+Changes to defaults using the preceding methods only apply to **future** sessions. This is because session variable resolution happens at session start time. To change a default value in an existing open session, set the variable explicitly with [`SET`]({% link {{ page.version.version }}/set-vars.md %}).
+{{site.data.alerts.end}}

src/current/_includes/v25.2/sql/session-variable-precedence-order.md

@@ -0,0 +1,15 @@
+When a [session]({% link {{ page.version.version }}/show-sessions.md %}) starts, CockroachDB determines the initial value of each [session variable]({% link {{ page.version.version }}/session-variables.md %}) by evaluating the settings in the following order (items earlier in the list take precedence over later items):
+
+1. [Connection string parameters]({% link {{ page.version.version }}/connection-parameters.md %}): A value supplied as a query parameter in the connection URL (for example, `.../movr?sslmode=disable&timezone=UTC`).
+1. [Per-role, per-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-role-in-a-specific-database): A value set by `ALTER ROLE {role_name} IN DATABASE {db_name} SET {var}={value}`.
+1. [Per-role, all-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-role): A value set by `ALTER ROLE {role_name} SET {var}={value}`.
+1. [All-role, per-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-specific-database): A value set by `ALTER ROLE ALL IN DATABASE {db_name} SET {var}={value}` or equivalently by `ALTER DATABASE {db_name} SET {var}={value}`.
+1. [Cluster-wide defaults for all roles and all databases]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users): A value set by `ALTER ROLE ALL SET {var}={value}`.
+
+If a session variable is not modified using any of the preceding methods, the built-in system default value is used. Note that the [`root` user]({% link {{ page.version.version }}/security-reference/authorization.md %}#root-user) is exempt from settings 3–5. The `root` user is only affected by values specified in the connection string.
+
+You can also set session variables for the duration of a single transaction by using [`SET LOCAL {var}={value}`]({% link {{ page.version.version }}/set-vars.md %}#set-a-variable-for-the-duration-of-a-single-transaction).
+
+{{site.data.alerts.callout_info}}
+Changes to defaults using the preceding methods only apply to **future** sessions. This is because session variable resolution happens at session start time. To change a default value in an existing open session, set the variable explicitly with [`SET`]({% link {{ page.version.version }}/set-vars.md %}).
+{{site.data.alerts.end}}

src/current/_includes/v25.3/sql/session-variable-precedence-order.md

@@ -0,0 +1,15 @@
+When a [session]({% link {{ page.version.version }}/show-sessions.md %}) starts, CockroachDB determines the initial value of each [session variable]({% link {{ page.version.version }}/session-variables.md %}) by evaluating the settings in the following order (items earlier in the list take precedence over later items):
+
+1. [Connection string parameters]({% link {{ page.version.version }}/connection-parameters.md %}): A value supplied as a query parameter in the connection URL (for example, `.../movr?sslmode=disable&timezone=UTC`).
+1. [Per-role, per-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-role-in-a-specific-database): A value set by `ALTER ROLE {role_name} IN DATABASE {db_name} SET {var}={value}`.
+1. [Per-role, all-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-role): A value set by `ALTER ROLE {role_name} SET {var}={value}`.
+1. [All-role, per-database defaults]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-a-specific-database): A value set by `ALTER ROLE ALL IN DATABASE {db_name} SET {var}={value}` or equivalently by `ALTER DATABASE {db_name} SET {var}={value}`.
+1. [Cluster-wide defaults for all roles and all databases]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users): A value set by `ALTER ROLE ALL SET {var}={value}`.
+
+If a session variable is not modified using any of the preceding methods, the built-in system default value is used. Note that the [`root` user]({% link {{ page.version.version }}/security-reference/authorization.md %}#root-user) is exempt from settings 3–5. The `root` user is only affected by values specified in the connection string.
+
+You can also set session variables for the duration of a single transaction by using [`SET LOCAL {var}={value}`]({% link {{ page.version.version }}/set-vars.md %}#set-a-variable-for-the-duration-of-a-single-transaction).
+
+{{site.data.alerts.callout_info}}
+Changes to defaults using the preceding methods only apply to **future** sessions. This is because session variable resolution happens at session start time. To change a default value in an existing open session, set the variable explicitly with [`SET`]({% link {{ page.version.version }}/set-vars.md %}).
+{{site.data.alerts.end}}

src/current/v24.1/alter-database.md

@@ -400,6 +400,10 @@ In CockroachDB, the following are aliases for `ALTER DATABASE ... SET {session v
 
 For more information, refer to [`ALTER ROLE ALL ...`]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users).
 
+#### Session variable precedence
+
+{% include {{ page.version.version }}/sql/session-variable-precedence-order.md %}
+
 ### `SET PRIMARY REGION`
 
 `ALTER DATABASE .. SET PRIMARY REGION` sets the primary [region]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions) of a [multi-region database]({% link {{ page.version.version }}/multiregion-overview.md %}).

src/current/v24.1/alter-role.md

@@ -11,7 +11,13 @@ You can use the keywords `ROLE` and `USER` interchangeably. [`ALTER USER`]({% li
 
 ## Considerations
 
-- Password creation and alteration is supported only in secure clusters.
+### Password management
+
+Password creation and alteration is supported only in secure clusters.
+
+### Session variable precedence
+
+{% include {{ page.version.version }}/sql/session-variable-precedence-order.md %}
 
 ## Required privileges
 

src/current/v24.1/session-variables.md

@@ -5,14 +5,18 @@ toc: true
 docs_area: reference.sql
 ---
 
-The [`SET`]({% link {{ page.version.version }}/set-vars.md %}) statement can modify one of the session configuration variables. These can also be queried via [`SHOW`]({% link {{ page.version.version }}/show-vars.md %}). By default, session variable values are set for the duration of the current session.
-
-CockroachDB supports setting session variables for the duration of a single transaction, using [the `LOCAL` keyword]({% link {{ page.version.version }}/set-vars.md %}#set-local).
+The [`SET`]({% link {{ page.version.version }}/set-vars.md %}) statement can modify one of the session configuration variables. These can also be queried via [`SHOW`]({% link {{ page.version.version }}/show-vars.md %}).
 
 ## Supported variables
 
 {% include {{ page.version.version }}/misc/session-vars.md %}
 
+## Considerations
+
+### Session variable precedence
+
+{% include {{ page.version.version }}/sql/session-variable-precedence-order.md %}
+
 ## See also
 
 - [`SET {session variable}`]({% link {{ page.version.version }}/set-vars.md %})

src/current/v24.1/set-vars.md

@@ -5,9 +5,7 @@ toc: true
 docs_area: reference.sql
 ---
 
-The `SET` [statement]({% link {{ page.version.version }}/sql-statements.md %}) can modify one of the session configuration variables. These can also be queried via [`SHOW`]({% link {{ page.version.version }}/show-vars.md %}). By default, session variable values are set for the duration of the current session.
-
-CockroachDB supports setting session variables for the duration of a single transaction, using [the `LOCAL` keyword](#set-local).
+The `SET` [statement]({% link {{ page.version.version }}/sql-statements.md %}) can modify one of the session configuration variables. These can also be queried via [`SHOW`]({% link {{ page.version.version }}/show-vars.md %}). By default, session variable values are set for all future sessions to the database; they do not affect the current session.
 
 {{site.data.alerts.callout_info}}
 The `SET` statement for session variables is unrelated to the other [`SET TRANSACTION`]({% link {{ page.version.version }}/set-transaction.md %}) and [`SET CLUSTER SETTING`]({% link {{ page.version.version }}/cluster-settings.md %}#change-a-cluster-setting) statements.
@@ -452,6 +450,12 @@ When setting a time zone, note the following:
 `kv`  | Same as `cluster` except that "kv messages" are collected instead of regular trace messages. See [`SHOW TRACE FOR SESSION`]({% link {{ page.version.version }}/show-trace.md %}).
 `results` | Result rows and row counts are copied to the session trace. This must be specified in order for the output of a query to be printed in the session trace.<br><br>Example: `SET tracing = kv, results;`
 
+## Considerations
+
+### Session variable precedence
+
+{% include {{ page.version.version }}/sql/session-variable-precedence-order.md %}
+
 ## Known Limitations
 
 {% include {{page.version.version}}/known-limitations/set-transaction-no-rollback.md %}

src/current/v24.3/alter-database.md

@@ -400,6 +400,10 @@ In CockroachDB, the following are aliases for `ALTER DATABASE ... SET {session v
 
 For more information, refer to [`ALTER ROLE ALL ...`]({% link {{ page.version.version }}/alter-role.md %}#set-default-session-variable-values-for-all-users).
 
+#### Session variable precedence
+
+{% include {{ page.version.version }}/sql/session-variable-precedence-order.md %}
+
 ### `SET PRIMARY REGION`
 
 `ALTER DATABASE .. SET PRIMARY REGION` sets the primary [region]({% link {{ page.version.version }}/multiregion-overview.md %}#database-regions) of a [multi-region database]({% link {{ page.version.version }}/multiregion-overview.md %}).