Add docs for Row-level security (RLS)

Fixes DOC-10439, DOC-12948

Summary of changes:

- Add 'Row-level security' overview page
- Add or update SQL statement docs for:
  - `CREATE POLICY`
  - `ALTER POLICY`
  - `DROP POLICY`
  - `SHOW POLICIES`
  - `ALTER TABLE {ENABLE,DISABLE} ROW LEVEL SECURITY`
  - `ALTER TABLE {FORCE,UNFORCE} ROW LEVEL SECURITY`
  - `CREATE ROLE ... WITH BYPASSRLS`
  - `ALTER ROLE ... WITH BYPASSRLS`

Author: rmloveland

src/current/_includes/v25.2/sidebar-data/reference.json

@@ -382,6 +382,12 @@
               "/${VERSION}/column-level-encryption.html"
             ]
           },
+          {
+            "title": "Row-level Security",
+            "urls": [
+              "/${VERSION}/row-level-security.html"
+            ]
+          },
           {
             "title": "PKI and TLS",
             "urls": [

src/current/_includes/v25.2/sidebar-data/sql.json

@@ -64,6 +64,12 @@
                 "/${VERSION}/alter-partition.html"
               ]
             },
+            {
+              "title": "<code>ALTER POLICY</code>",
+              "urls": [
+                "/${VERSION}/alter-policy.html"
+              ]
+            },
             {
               "title": "<code>ALTER PROCEDURE</code>",
               "urls": [
@@ -220,6 +226,12 @@
                 "/${VERSION}/create-logical-replication-stream.html"
               ]
             },
+            {
+              "title": "<code>CREATE POLICY</code>",
+              "urls": [
+                "/${VERSION}/create-policy.html"
+              ]
+            },
             {
               "title": "<code>CREATE PROCEDURE</code>",
               "urls": [
@@ -340,6 +352,12 @@
                  "/${VERSION}/drop-owned-by.html"
                ]
              },
+            {
+              "title": "<code>DROP POLICY</code>",
+              "urls": [
+                "/${VERSION}/drop-policy.html"
+              ]
+            },
             {
                "title": "<code>DROP TRIGGER</code>",
                "urls": [
@@ -694,6 +712,12 @@
                 "/${VERSION}/show-partitions.html"
               ]
             },
+            {
+              "title": "<code>SHOW POLICIES</code>",
+              "urls": [
+                "/${VERSION}/show-policies.html"
+              ]
+            },
             {
               "title": "<code>SHOW RANGES</code>",
               "urls": [

src/current/_includes/v25.2/sql/privileges.md

@@ -2,6 +2,7 @@ Privilege | Levels | Description
 ----------|--------|------------
 `ALL` | System, Database, Schema, Table, Sequence, Type | For the object to which `ALL` is applied, grants all privileges at the system, database, schema, table, sequence, or type level.
 `BACKUP` | System, Database, Table | Grants the ability to create [backups]({% link {{ page.version.version }}/backup-and-restore-overview.md %}) at the system, database, or table level.
+`BYPASSRLS` | [XXX](XXX): XXX (NEW IN v25.2) Grants the ability to bypass [row-level security (RLS)]({% link {{ page.version.version }}/row-level-security.md %}) policies on a table, granting unrestricted read and write access to all rows.
 `CANCELQUERY` | System | Grants the ability to cancel queries.
 `CHANGEFEED` | Table | Grants the ability to create [changefeeds]({% link {{ page.version.version }}/change-data-capture-overview.md %}) on a table.
 <a id="connect"></a>`CONNECT` | Database | Grants the ability to view a database's metadata, which consists of objects in a database's `information_schema` and `pg_catalog` system catalogs. This allows the role to view the database's table, schemas, user-defined types, and list the database when running `SHOW DATABASES`. The `CONNECT` privilege is also required to run backups of the database.

src/current/_includes/v25.2/sql/role-options.md

@@ -1,5 +1,6 @@
 Role option | Description
 ------------|-------------
+`BYPASSRLS`/`NOBYPASSRLS` | **New in v25.2** [XXX](XXX):Grants the ability to bypass [row-level security (RLS)]({% link {{ page.version.version }}/row-level-security.md %}) policies on a table, granting unrestricted read and write access to all rows.
 `CANCELQUERY`/`NOCANCELQUERY` | **Deprecated in v22.2: Use the `CANCELQUERY` [system privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges).** Allow or disallow a role to cancel [queries]({% link {{ page.version.version }}/cancel-query.md %}) and [sessions]({% link {{ page.version.version }}/cancel-session.md %}) of other roles. Without this role option, roles can only cancel their own queries and sessions. Even with the `CANCELQUERY` role option, non-`admin` roles cannot cancel `admin` queries or sessions. This option should usually be combined with `VIEWACTIVITY` so that the role can view other roles' query and session information. <br><br>By default, the role option is set to `NOCANCELQUERY` for all non-`admin` roles.
 `CONTROLCHANGEFEED`/`NOCONTROLCHANGEFEED` | **Deprecated in v23.1: Use the `CHANGEFEED` [privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges).** Allow or disallow a role to run [`CREATE CHANGEFEED`]({% link {{ page.version.version }}/create-changefeed.md %}) on tables they have `SELECT` privileges on. <br><br>By default, the role option is set to `NOCONTROLCHANGEFEED` for all non-`admin` roles.
 `CONTROLJOB`/`NOCONTROLJOB` | Allow or disallow a role to [pause]({% link {{ page.version.version }}/pause-job.md %}), [resume]({% link {{ page.version.version }}/resume-job.md %}), and [cancel]({% link {{ page.version.version }}/cancel-job.md %}) jobs. Non-`admin` roles cannot control jobs created by `admin` roles. <br><br>By default, the role option is set to `NOCONTROLJOB` for all non-`admin` roles.

src/current/v25.2/alter-policy.md

@@ -0,0 +1,38 @@
+---
+title: ALTER POLICY
+summary: The ALTER POLICY statement ... XXX
+toc: true
+docs_area: reference.sql
+---
+
+The `ALTER POLICY` statement changes the [row-level security (RLS)]({% link {{ page.version.version }}/enum.md %}) policies for ... [XXX](XXX): XXX
+
+## Syntax
+
+[xxx](): this diagram not getting built/added to https://github.com/cockroachdb/generated-diagrams/tree/master/grammar_svg for some reason
+
+<div>
+{% remote_include https://github.com/raw/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/alter_policy_stmt.html %}
+</div>
+
+## Parameters
+
+[XXX](XXX): XXX
+
+Parameter | Description
+----------|------------
+[XXX](XXX): XXX       | [XXX](XXX): XXX
+
+## Examples
+
+[XXX](XXX): XXX
+
+## See also
+
+- [Row-level security (RLS) overview]({% link {{ page.version.version }}/row-level-security.md %})
+- [`CREATE POLICY`]({% link {{ page.version.version }}/create-policy.md %})
+- [`DROP POLICY`]({% link {{ page.version.version }}/drop-policy.md %})
+- [`SHOW POLICIES`]({% link {{ page.version.version }}/show-policies.md %})
+- [`ALTER TABLE {ENABLE, DISABLE} ROW LEVEL SECURITY`]({% link {{ page.version.version }}/alter-table.md %}#enable-disable-row-level-security)
+- [`ALTER ROLE ... WITH BYPASSRLS`]({% link {{ page.version.version }}/alter-role.md %}#allow-a-role-to-bypass-row-level-security-rls)
+- [`CREATE ROLE ... WITH BYPASSRLS`]({% link {{ page.version.version }}/create-role.md %}#create-a-role-that-can-bypass-row-level-security-rls)

src/current/v25.2/alter-role.md

@@ -50,7 +50,12 @@ The following statements are run by the `root` user that is a member of the `adm
 The following example allows a role to log in to the database with a [password]({% link {{ page.version.version }}/authentication.md %}#client-authentication):
 
 ~~~ sql
-root@:26257/defaultdb> ALTER ROLE carl WITH LOGIN PASSWORD 'An0ther$tr0nGpassW0rD' VALID UNTIL '2021-10-10';
+CREATE ROLE carl;
+~~~
+
+~~~ sql
+-- sqlchecker: ignore
+ALTER ROLE carl WITH LOGIN PASSWORD 'An0ther$tr0nGpassW0rD' VALID UNTIL '2021-10-10';
 ~~~
 
 ### Prevent a role from using password authentication
@@ -59,73 +64,77 @@ The following statement prevents the user from using password authentication and
 
 {% include_cached copy-clipboard.html %}
 ~~~ sql
-root@:26257/defaultdb> ALTER ROLE carl WITH PASSWORD NULL;
+ALTER ROLE carl WITH PASSWORD NULL;
 ~~~
 
 ### Allow a role to create other roles and manage authentication methods for the new roles
 
 The following example allows the role to [create other roles]({% link {{ page.version.version }}/create-role.md %}) and [manage authentication methods]({% link {{ page.version.version }}/authentication.md %}#client-authentication) for them:
 
 ~~~ sql
-root@:26257/defaultdb> ALTER ROLE carl WITH CREATEROLE CREATELOGIN;
+ALTER ROLE carl WITH CREATEROLE CREATELOGIN;
 ~~~
 
 ### Allow a role to create and rename databases
 
 The following example allows the role to [create]({% link {{ page.version.version }}/create-database.md %}) or [rename]({% link {{ page.version.version }}/alter-database.md %}#rename-to) databases:
 
 ~~~ sql
-root@:26257/defaultdb> ALTER ROLE carl WITH CREATEDB;
+ALTER ROLE carl WITH CREATEDB;
 ~~~
 
 ### Allow a role to pause, resume, and cancel non-admin jobs
 
 The following example allows the role to [pause]({% link {{ page.version.version }}/pause-job.md %}), [resume]({% link {{ page.version.version }}/resume-job.md %}), and [cancel]({% link {{ page.version.version }}/cancel-job.md %}) jobs:
 
 ~~~ sql
-root@:26257/defaultdb> ALTER ROLE carl WITH CONTROLJOB;
+ALTER ROLE carl WITH CONTROLJOB;
 ~~~
 
 ### Allow a role to see and cancel non-admin queries and sessions
 
 The following example allows the role to cancel [queries]({% link {{ page.version.version }}/cancel-query.md %}) and [sessions]({% link {{ page.version.version }}/cancel-session.md %}) for other non-`admin` roles:
 
 ~~~ sql
-root@:26257/defaultdb> ALTER ROLE carl WITH CANCELQUERY VIEWACTIVITY;
+ALTER ROLE carl WITH CANCELQUERY VIEWACTIVITY;
 ~~~
 
 ### Allow a role to control changefeeds
 
 The following example allows the role to run [`CREATE CHANGEFEED`]({% link {{ page.version.version }}/create-changefeed.md %}):
 
 ~~~ sql
-root@:26257/defaultdb> ALTER ROLE carl WITH CONTROLCHANGEFEED;
+ALTER ROLE carl WITH CONTROLCHANGEFEED;
 ~~~
 
 ### Allow a role to modify cluster settings
 
 The following example allows the role to modify [cluster settings]({% link {{ page.version.version }}/cluster-settings.md %}):
 
 ~~~ sql
-root@:26257/defaultdb> ALTER ROLE carl WITH MODIFYCLUSTERSETTING;
+ALTER ROLE carl WITH MODIFYCLUSTERSETTING;
 ~~~
 
+### Allow a role to bypass row-level security (RLS)
+
+[XXX](XXX): XXX
+
 ### Set default session variable values for a role
 
 In the following example, the `root` user creates a role named `max`, and sets the default value of the `timezone` [session variable]({% link {{ page.version.version }}/set-vars.md %}#supported-variables) for the `max` role.
 
 ~~~ sql
-root@:26257/defaultdb> CREATE ROLE max WITH LOGIN;
+CREATE ROLE max WITH LOGIN;
 ~~~
 
 ~~~ sql
-root@:26257/defaultdb> ALTER ROLE max SET timezone = 'America/New_York';
+ALTER ROLE max SET timezone = 'America/New_York';
 ~~~
 
 This statement does not affect the default `timezone` value for any role other than `max`:
 
 ~~~ sql
-root@:26257/defaultdb> SHOW timezone;
+SHOW timezone;
 ~~~
 
 ~~~
@@ -138,7 +147,7 @@ root@:26257/defaultdb> SHOW timezone;
 To see the default `timezone` value for the `max` role, run the `SHOW` statement as a member of the `max` role:
 
 ~~~ sql
-max@:26257/defaultdb> SHOW timezone;
+SHOW timezone;
 ~~~
 
 ~~~
@@ -155,21 +164,21 @@ max@:26257/defaultdb> SHOW timezone;
 In the following example, the `root` user creates a role named `max` and a database named `movr`, and sets the default value of the `statement_timeout` [session variable]({% link {{ page.version.version }}/set-vars.md %}#supported-variables) for the `max` role in the `movr` database.
 
 ~~~ sql
-root@:26257/defaultdb> CREATE DATABASE movr;
+CREATE DATABASE IF NOT EXISTS movr;
 ~~~
 
 ~~~ sql
-root@:26257/defaultdb> CREATE ROLE max WITH LOGIN;
+CREATE ROLE IF NOT EXISTS max WITH LOGIN;
 ~~~
 
 ~~~ sql
-root@:26257/defaultdb> ALTER ROLE max IN DATABASE movr SET statement_timeout = '10s';
+ALTER ROLE max IN DATABASE movr SET statement_timeout = '10s';
 ~~~
 
 This statement does not affect the default `statement_timeout` value for any role other than `max`, or in any database other than `movr`.
 
 ~~~ sql
-root@:26257/defaultdb> SHOW statement_timeout;
+SHOW statement_timeout;
 ~~~
 
 ~~~
@@ -186,7 +195,7 @@ cockroach sql --url 'postgresql://max@localhost:26257/movr?sslmode=disable'
 ~~~
 
 ~~~ sql
-max@:26257/movr> SHOW statement_timeout;
+SHOW statement_timeout;
 ~~~
 
 ~~~
@@ -203,11 +212,11 @@ max@:26257/movr> SHOW statement_timeout;
 In the following example, the `root` user creates a database named `movr`, and sets the default value of the `timezone` [session variable]({% link {{ page.version.version }}/set-vars.md %}#supported-variables) for all roles in that database.
 
 ~~~ sql
-root@:26257/defaultdb> CREATE DATABASE movr;
+CREATE DATABASE IF NOT EXISTS movr;
 ~~~
 
 ~~~ sql
-root@:26257/defaultdb> ALTER ROLE ALL IN DATABASE movr SET timezone = 'America/New_York';
+ALTER ROLE ALL IN DATABASE movr SET timezone = 'America/New_York';
 ~~~
 
 {{site.data.alerts.callout_info}}
@@ -217,7 +226,7 @@ This statement is identical to [`ALTER DATABASE movr SET timezone = 'America/New
 This statement does not affect the default `timezone` value for any database other than `movr`:
 
 ~~~ sql
-root@:26257/defaultdb> SHOW timezone;
+SHOW timezone;
 ~~~
 
 ~~~
@@ -230,7 +239,7 @@ root@:26257/defaultdb> SHOW timezone;
 To see the default `timezone` value for the `max` role, run the `SHOW` statement as a member of the `max` role:
 
 ~~~ sql
-root@:26257/movr> SHOW timezone;
+SHOW timezone;
 ~~~
 
 ~~~
@@ -265,7 +274,7 @@ ALTER ROLE
 
 {% include_cached copy-clipboard.html %}
 ~~~ sql
-ALTER ROLE maxroach WITH SUBJECT 'CN=myName2,OU=myOrgUnit2,O=myOrg2,L=myLocality2,ST=myState2,C=myCountry2' LOGIN;
+ALTER ROLE max WITH SUBJECT 'CN=myName2,OU=myOrgUnit2,O=myOrg2,L=myLocality2,ST=myState2,C=myCountry2' LOGIN;
 ~~~
 
 {% include {{page.version.version}}/misc/cert-auth-using-x509-subject.md %}
@@ -280,3 +289,12 @@ ALTER ROLE maxroach WITH SUBJECT 'CN=myName2,OU=myOrgUnit2,O=myOrg2,L=myLocality
 - [SQL Statements]({% link {{ page.version.version }}/sql-statements.md %})
 - [Authorization Best Practices]({% link {{ page.version.version }}/security-reference/authorization.md %}#authorization-best-practices)
 - [`SHOW DEFAULT SESSION VARIABLES FOR ROLE`]({% link {{ page.version.version }}/show-default-session-variables-for-role.md %})
+
+<!-- sqlchecker test block -->
+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+DROP ROLE carl;
+DROP ROLE max;
+DROP DATABASE movr;
+~~~

src/current/v25.2/alter-table.md

@@ -59,6 +59,8 @@ Subcommand | Description | Can combine with other subcommands?
 [`RENAME CONSTRAINT`](#rename-constraint) | Change constraints columns. | Yes
 [`RENAME TO`](#rename-to) | Change the names of tables. | No
 [`RESET {storage parameter}`](#reset-storage-parameter) | Reset a storage parameter on a table to its default value. | Yes
+[`{ENABLE, DISABLE} ROW LEVEL SECURITY`](#enable-disable-row-level-security) | [XXX](XXX): XXX | No
+[`{FORCE, UNFORCE} ROW LEVEL SECURITY`](#force-unforce-row-level-security) | [XXX](XXX): XXX | No
 [`SET {storage parameter}`](#set-storage-parameter) | Set a storage parameter on a table. | Yes
 [`SET LOCALITY`](#set-locality) |  Set the table locality for a table in a [multi-region database]({% link {{ page.version.version }}/multiregion-overview.md %}). | No
 [`SET SCHEMA`](#set-schema) |  Change the [schema]({% link {{ page.version.version }}/sql-name-resolution.md %}) of a table. | No
@@ -468,6 +470,34 @@ Parameter | Description |
 
 For usage, see [Synopsis](#synopsis).
 
+### `{ENABLE, DISABLE} ROW LEVEL SECURITY`
+
+[XXX](XXX): XXX
+
+#### Required privileges
+
+[XXX](XXX): GET THIS REVIEWED
+
+The user must be a member of the [`admin`]({% link {{ page.version.version }}/security-reference/authorization.md %}#roles) or [owner]({% link {{ page.version.version }}/security-reference/authorization.md %}#object-ownership) roles, or have the [`BYPASSRLS` privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the table.
+
+#### Parameters
+
+[XXX](XXX): XXX
+
+### `{FORCE, UNFORCE} ROW LEVEL SECURITY`
+
+[XXX](XXX): XXX
+
+#### Required privileges
+
+[XXX](XXX): GET THIS REVIEWED
+
+The user must be a member of the [`admin`]({% link {{ page.version.version }}/security-reference/authorization.md %}#roles) or [owner]({% link {{ page.version.version }}/security-reference/authorization.md %}#object-ownership) roles, or have the [`BYPASSRLS` privilege]({% link {{ page.version.version }}/security-reference/authorization.md %}#supported-privileges) on the table.
+
+#### Parameters
+
+[XXX](XXX): XXX
+
 ### `SET {storage parameter}`
 
 `ALTER TABLE ... SET {storage parameter}` sets a storage parameter on an existing table.

src/current/v25.2/create-policy.md

@@ -0,0 +1,36 @@
+---
+title: CREATE POLICY
+summary: The CREATE POLICY statement ... XXX
+toc: true
+docs_area: reference.sql
+---
+
+The `CREATE POLICY` statement changes the [row-level security (RLS)]({% link {{ page.version.version }}/enum.md %}) policies for ... [XXX](XXX): XXX
+
+## Syntax
+
+[xxx](): this diagram not getting built/added to https://github.com/cockroachdb/generated-diagrams/tree/master/grammar_svg for some reason
+
+<div>
+{% remote_include https://github.com/raw/cockroachdb/generated-diagrams/{{ page.release_info.crdb_branch_name }}/grammar_svg/create_policy_stmt.html %}
+</div>
+
+## Parameters
+
+Parameter | Description
+----------|------------
+[XXX](XXX): XXX       | [XXX](XXX): XXX
+
+## Examples
+
+[XXX](XXX): XXX
+
+## See also
+
+- [Row-level security (RLS) overview]({% link {{ page.version.version }}/row-level-security.md %})
+- [`ALTER POLICY`]({% link {{ page.version.version }}/alter-policy.md %})
+- [`DROP POLICY`]({% link {{ page.version.version }}/drop-policy.md %})
+- [`SHOW POLICIES`]({% link {{ page.version.version }}/show-policies.md %})
+- [`ALTER TABLE {ENABLE, DISABLE} ROW LEVEL SECURITY`]({% link {{ page.version.version }}/alter-table.md %}#enable-disable-row-level-security)
+- [`ALTER ROLE ... WITH BYPASSRLS`]({% link {{ page.version.version }}/alter-role.md %}#allow-a-role-to-bypass-row-level-security-rls)
+- [`CREATE ROLE ... WITH BYPASSRLS`]({% link {{ page.version.version }}/create-role.md %}#create-a-role-that-can-bypass-row-level-security-rls)