Update docs for row_security session variable (#20764)

* Update docs for `row_security` session variable

Fixes DOC-15036

* Update with florence-crl feedback (1)

Author: rmloveland

src/current/_includes/v26.1/misc/session-vars.md

@@ -70,6 +70,7 @@
 | <a id="prefer-lookup-joins-for-fks"></a> `prefer_lookup_joins_for_fks` | If `on`, the optimizer prefers [`lookup joins`]({% link {{ page.version.version }}/joins.md %}#lookup-joins) to [`merge joins`]({% link {{ page.version.version }}/joins.md %}#merge-joins) when performing [`foreign key`]({% link {{ page.version.version }}/foreign-key.md %}) checks. | `off` | Yes | Yes |
 | <a id="reorder-joins-limit"></a> `reorder_joins_limit` | Maximum number of joins that the optimizer will attempt to reorder when searching for an optimal query execution plan. <br/><br/>For more information, see [Join reordering]({% link {{ page.version.version }}/cost-based-optimizer.md %}#join-reordering). | `8` | Yes | Yes |
 | <a id="require-explicit-primary-keys"></a> `require_explicit_primary_keys` | If `on`, CockroachDB throws an error for all tables created without an explicit primary key defined. | `off` | Yes | Yes |
+| <a id="row-security"></a> `row_security` | Controls whether queries in the current [session]({% link {{ page.version.version }}/show-sessions.md %}) should silently honor row-level security (RLS) policies or signal an error when those policies would filter out rows. | `on` | Yes | Yes |
 | <a id="search-path"></a> `search_path` | A list of schemas that will be searched to resolve unqualified table or function names. <br/>For more details, see [SQL name resolution]({% link {{ page.version.version }}/sql-name-resolution.md %}). | `public` | Yes | Yes |
 | <a id="serial-normalization"></a> `serial_normalization` | Specifies the default handling of [`SERIAL`]({% link {{ page.version.version }}/serial.md %}) in table definitions. Valid options include `'rowid'`, `'virtual_sequence'`, `sql_sequence`, `sql_sequence_cached`, [`sql_sequence_cached_node`]({% link {{ page.version.version }}/create-sequence.md %}#per-node-cache), and `unordered_rowid`. <br/>If set to `'virtual_sequence'`, the `SERIAL` type auto-creates a sequence for [better compatibility with Hibernate sequences](https://forum.cockroachlabs.com/t/hibernate-sequence-generator-returns-negative-number-and-ignore-unique-rowid/1885). <br/>If set to `sql_sequence_cached` or `sql_sequence_cached_node`, you can use the `sql.defaults.serial_sequences_cache_size` [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) to control the number of values to cache in a user's session, with a default of 256. <br/>If set to `unordered_rowid`, the `SERIAL` type generates a globally unique 64-bit integer (a combination of the insert timestamp and the ID of the node executing the statement) that does not have unique ordering. | `'rowid'` | Yes | Yes |
 | <a id="server-version"></a> `server_version` | The version of PostgreSQL that CockroachDB emulates. | Version-dependent | No | Yes |
@@ -110,7 +111,6 @@ The following session variables are exposed only for backwards compatibility wit
 | <a id="integer-datetimes"></a> `integer_datetimes` | `on` | No | Yes |
 | <a id="max-identifier-length"></a> `max_identifier_length` | `128` | No | Yes |
 | <a id="max-index-keys"></a> `max_index_keys` | `32` | No | Yes |
-| <a id="row-security"></a> `row_security` | `off` | No | Yes |
 | <a id="standard-conforming-strings"></a> `standard_conforming_strings` | `on` | No | Yes |
 | <a id="server-encoding"></a> `server_encoding` | `UTF8` | Yes | Yes |
 | <a id="synchronize-seqscans"></a> `synchronize_seqscans` | `on` | No | Yes |

src/current/v26.1/row-level-security.md

@@ -128,6 +128,26 @@ For examples, refer to:
 - [`ALTER TABLE ... ENABLE ROW LEVEL SECURITY`]({% link {{ page.version.version }}/alter-table.md %}#enable-row-level-security).
 - [`ALTER TABLE ... FORCE ROW LEVEL SECURITY`]({% link {{ page.version.version }}/alter-table.md %}#force-row-level-security).
 
+### Detect when row-level security is applied to a query
+
+The [`row_security` session variable]({% link {{ page.version.version }}/session-variables.md %}#row-security) controls whether queries in the current [session]({% link {{ page.version.version }}/show-sessions.md %}) should silently honor RLS policies or signal an error when those policies would filter out rows.
+
+The variable defaults to `on`, which applies policies as normal. Setting it to `off` lets non-[admin]({% link {{ page.version.version }}/security-reference/authorization.md %}#admin-role) users detect when an RLS policy would alter their results by returning an error instead of silently filtering rows. Admin users and table owners remain exempt from RLS by default regardless of this setting. To force table owners to be subject to RLS, you must use [`ALTER TABLE ... FORCE ROW LEVEL SECURITY`]({% link {{ page.version.version }}/alter-table.md %}#force-row-level-security).
+
+The following example shows how this session setting works:
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+-- Enable RLS error detection for the current session.
+SET row_security = off;
+
+-- This query should signal an error if an applicable RLS policy would filter out rows.
+SELECT * FROM sensitive_table;
+
+-- Restore the default behavior.
+RESET row_security;
+~~~
+
 ### RLS for data security (fine-grained access control)
 
 In a fine-grained access control scenario, you will want to restrict access to specific rows within a table based on user [roles]({% link {{ page.version.version }}/security-reference/authorization.md %}#roles), attributes, or relationships defined within the data itself. This goes beyond table-level [`GRANT`]({% link {{ page.version.version }}/grant.md %}) permissions. Common examples include restricting access to salary information, personal data, or region-specific records.