Add docs for Row-level security (RLS) #19527

rmloveland · 2025-04-14T21:05:39Z

Fixes DOC-10439, DOC-12948

Summary of changes:

Add 'Row-level security' overview page
Add 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

github-actions · 2025-04-14T21:06:02Z

Files changed:

src/current/_includes/v25.2/sidebar-data/reference.json
src/current/_includes/v25.2/sidebar-data/sql.json
src/current/_includes/v25.2/sql/privileges.md:

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

netlify · 2025-04-14T21:06:18Z

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

Name	Link
🔨 Latest commit	`faa5864`
🔍 Latest deploy log	https://app.netlify.com/sites/cockroachdb-interactivetutorials-docs/deploys/6822186133a824000878dca9

netlify · 2025-04-14T21:07:40Z

✅ Deploy Preview for cockroachdb-api-docs canceled.

Name	Link
🔨 Latest commit	`faa5864`
🔍 Latest deploy log	https://app.netlify.com/sites/cockroachdb-api-docs/deploys/68221861e432c3000838c0fa

netlify · 2025-04-14T21:15:02Z

❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →

Name	Link
🔨 Latest commit	`faa5864`
🔍 Latest deploy log	https://app.netlify.com/sites/cockroachdb-docs/deploys/682218611503cf0008c3faf9

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`

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

spilchen · 2025-05-06T14:42:29Z

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.
+<a name="bypassrls"></a> `BYPASSRLS` | **New in v25.2** Grants the ability for a role to bypass [row-level security (RLS)]({% link {{ page.version.version }}/row-level-security.md %}) policies on a table using the `BYPASSRLS`/`NOBYPASSRLS` role options, granting unrestricted read and write access to all rows.


We talk about BYPASSRLS as a role option. Yet, this is the page for system privileges. I treat them separately from role options.

ok thanks for clearing up my confusion there; removed this from the system privs and it's now only in the role options

I want to clarify that BYPASSRLS can be used as a system privilege. What tripped me up was referring to it as a role option. I think we should include it on the privileges page, but with slightly adjusted wording to reflect this distinction.

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

src/current/v25.2/row-level-security.md

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

spilchen · 2025-05-06T18:48:36Z

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

+
+### Replace a Policy
+
+This example demonstrates dropping an existing policy before replacing it with a new one that has a different fundamental behavior (e.g., changing from `PERMISSIVE` to `RESTRICTIVE`), which cannot be done using [`ALTER POLICY`]({% link {{ page.version.version }}/alter-policy.md %}).


I feel like this is an overly complicated example. I wouldn't expect changing the type from PERMISSIVE to RESTRICTIVE (or vice-versa) be a common occurrence that it requires an example. Can we have a simpler example here?

Updated to just be a single, simple DROP POLICY example stmt

spilchen · 2025-05-06T18:56:48Z

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

+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT rolname FROM pg_roles WHERE rolbypassrls = true


I wasn't aware of this column in pg_roles. Currently, it always returns false. Even if the role has the BYPASSRLS option. I'm glad you included this example. I have opened issue cockroachdb/cockroach#146228

Nice, glad it was useful. Do you think we should remove this for now and add back in after the issue is addressed?

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

spilchen · 2025-05-06T19:05:45Z

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

+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT rolname FROM pg_roles WHERE rolbypassrls = true


Similar comment here about bug cockroachdb/cockroach#146228.

same q re: should we remove for now?

Yes, let's remove it. When we fix it, I'll make sure there is a release note included with that change so we can remember to add this back.

rmloveland · 2025-05-09T17:33:40Z

thanks for the review @spilchen, i've tried to address your feedback, this is RFAL - changes are in latest commit Update with spilchen feedback (1)

spilchen

This is looking good.

spilchen · 2025-05-09T21:36:45Z

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

+
+{% include_cached copy-clipboard.html %}
+~~~ sql
+SELECT rolname FROM pg_roles WHERE rolbypassrls = true


Yes, let's remove it. When we fix it, I'll make sure there is a release note included with that change so we can remember to add this back.

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

spilchen · 2025-05-09T21:42:21Z

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

+For examples, see [Force and unforce row-level security](#force-and-unforce-row-level-security).
+
+{{site.data.alerts.callout_danger}}
+Users with the `BYPASSRLS` [role option]({% link {{ page.version.version }}/security-reference/authorization.md %}#role-options) can still bypass RLS even when `ALTER TABLE ... FORCE ROW LEVEL SECURITY` is enabled. To see the roles with this option, run: `SELECT rolname FROM pg_roles WHERE rolbypassrls = true;`.


We should probably leave the last bit about looking up in pg_roles until we fix that issue.

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

src/current/v25.2/row-level-security.md

spilchen · 2025-05-09T22:31:13Z

src/current/v25.2/row-level-security.md

+
+When [views]({% link {{ page.version.version }}/views.md %}) are accessed, RLS policies on any underlying [tables]({% link {{ page.version.version }}/schema-design-table.md %}) are applied. [Policies]({% link {{ page.version.version }}/create-policy.md %}) can also be defined directly on views.
+
+Views use the [role]({% link {{ page.version.version }}/security-reference/authorization.md %}#roles) of the view owner to determine row-level security filters, **not** the role of the user executing the view. This can cause issues because the view owner may have entirely different policies than the user executing the view.


Yeah, the design document is wrong sorry. This found out late in the cycle. We tried to capture the current behaviour here: cockroachdb/cockroach#138918 (comment)

spilchen · 2025-05-09T22:46:34Z

src/current/v25.2/row-level-security.md

+    TO public
+    USING (tenant_id = split_part(current_setting('application_name', true), '.', 2)::UUID);
+
+CREATE POLICY tenant_isolation ON invoices


I’m not quite sure what the second policy is intended to show. At first glance, the expressions in both policies appear to be identical. While tenant_isolation_permissive doesn’t include an explicit WITH CHECK, it will still enforce the USING expression for INSERT and UPDATE, and that expression is the same as the WITH CHECK in the other policy.

The only notable difference is the role: one policy is for public, and the other is for app_dev. However, in the example, only the app_dev role is used—so we never really see a scenario where only the first policy applies.

If the goal is to demonstrate how multiple policies with different roles interact, a more illustrative example might involve a role that can read all tenants' data but cannot modify it. In contrast, the app_dev role would enforce tenant-level isolation for both reads and writes. Then, if a user had both roles—say, two users from app_dev and one of them also has this broader-access role—we could observe the combined effect of overlapping policies in action. This may still be a contrived example.

Another idea is to use the role for public to only show results for a default tenant. That way if the application_name is omitted, we still see results.

went with the latter suggestion b/c it seemed simpler. here is what i updated to, PTAL

CREATE POLICY tenant_isolation_permissive ON invoices AS PERMISSIVE FOR ALL TO public USING (tenant_id = COALESCE( -- Attempt to extract UUID after the last '.' in application_name -- Handle cases where setting is missing, empty, or has no '.' NULLIF(split_part(current_setting('application_name', true), '.', 2), '')::UUID, -- Default Tenant ID 'ad7b4529-f5d6-4d0e-8b0f-91af455a70e5' ) );

with the following extra explanation

- `AS PERMISSIVE`: Necessary because you need at least one permissive policy. The permissive policy above has logic to show results for a default tenant ID if the `application_name` is omitted or improperly formatted.

spilchen · 2025-05-09T22:53:17Z

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

@@ -1,5 +1,6 @@
 Role option | Description
 ------------|-------------
+<a name="bypassrls"></a> `BYPASSRLS`/`NOBYPASSRLS` | **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. This option controls the access from an RLS perspective only; the user also needs sufficient [`GRANT`]({% link {{ page.version.version }}/grant.md %}) privileges to read or write to the table.


We should mention BYPASSRLS in system privileges. You had it in earlier that I commented on. But I think there was a misunderstanding of my comment, and the entire mention was removed.

ah my bad

went back and looked at your previous comment which was about us not talking about role options in the system privilege description. here's the updated version

BYPASSRLS | Table | 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. This privilege controls the access from an RLS perspective only; the user also needs sufficient [GRANT]({% link {{ page.version.version }}/grant.md %}) privileges to read or write to the table.

rmloveland · 2025-05-12T15:51:23Z

thanks for the additional comments @spilchen , this is RFAL again!

rmloveland marked this pull request as draft April 14, 2025 21:05

rmloveland force-pushed the 20250414-DOC-10439-row-level-security branch 7 times, most recently from dc16ae3 to 2cb3af9 Compare April 23, 2025 15:50

rmloveland force-pushed the 20250414-DOC-10439-row-level-security branch 9 times, most recently from 56780c5 to f07bb90 Compare May 1, 2025 14:32

rmloveland force-pushed the 20250414-DOC-10439-row-level-security branch 4 times, most recently from 181509f to 0046485 Compare May 5, 2025 19:08

rmloveland marked this pull request as ready for review May 5, 2025 19:30

rmloveland force-pushed the 20250414-DOC-10439-row-level-security branch from 0046485 to 20ddc91 Compare May 5, 2025 19:32

rmloveland requested review from spilchen and rafiss May 5, 2025 19:32

rmloveland requested a review from dikshant May 5, 2025 19:32

spilchen requested changes May 6, 2025

View reviewed changes

Update with spilchen feedback (1)

e3ef524

rmloveland requested a review from spilchen May 9, 2025 17:32

spilchen reviewed May 9, 2025

View reviewed changes

rmloveland requested a review from taroface May 12, 2025 14:05

Update with spilchen feedback (2)

faa5864

rmloveland requested a review from spilchen May 12, 2025 15:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add docs for Row-level security (RLS) #19527

Add docs for Row-level security (RLS) #19527

rmloveland commented Apr 14, 2025 •

edited

Loading

github-actions bot commented Apr 14, 2025 •

edited

Loading

netlify bot commented Apr 14, 2025 •

edited

Loading

netlify bot commented Apr 14, 2025 •

edited

Loading

netlify bot commented Apr 14, 2025 •

edited

Loading

spilchen May 6, 2025

rmloveland May 8, 2025

spilchen May 9, 2025

spilchen May 6, 2025

rmloveland May 9, 2025

spilchen May 6, 2025

rmloveland May 9, 2025

spilchen May 6, 2025

rmloveland May 9, 2025

spilchen May 9, 2025

rmloveland commented May 9, 2025

spilchen left a comment

spilchen May 9, 2025

spilchen May 9, 2025

spilchen May 9, 2025

spilchen May 9, 2025

rmloveland May 12, 2025

spilchen May 9, 2025

rmloveland May 12, 2025

rmloveland commented May 12, 2025


		### Replace a Policy

		This example demonstrates dropping an existing policy before replacing it with a new one that has a different fundamental behavior (e.g., changing from `PERMISSIVE` to `RESTRICTIVE`), which cannot be done using [`ALTER POLICY`]({% link {{ page.version.version }}/alter-policy.md %}).


		When [views]({% link {{ page.version.version }}/views.md %}) are accessed, RLS policies on any underlying [tables]({% link {{ page.version.version }}/schema-design-table.md %}) are applied. [Policies]({% link {{ page.version.version }}/create-policy.md %}) can also be defined directly on views.

		Views use the [role]({% link {{ page.version.version }}/security-reference/authorization.md %}#roles) of the view owner to determine row-level security filters, not the role of the user executing the view. This can cause issues because the view owner may have entirely different policies than the user executing the view.

Add docs for Row-level security (RLS) #19527

Are you sure you want to change the base?

Add docs for Row-level security (RLS) #19527

Conversation

rmloveland commented Apr 14, 2025 • edited Loading

github-actions bot commented Apr 14, 2025 • edited Loading

Files changed:

netlify bot commented Apr 14, 2025 • edited Loading

✅ Deploy Preview for cockroachdb-interactivetutorials-docs canceled.

netlify bot commented Apr 14, 2025 • edited Loading

✅ Deploy Preview for cockroachdb-api-docs canceled.

netlify bot commented Apr 14, 2025 • edited Loading

❌ Deploy Preview for cockroachdb-docs failed. Why did it fail? →

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rmloveland commented May 9, 2025

spilchen left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rmloveland commented May 12, 2025

rmloveland commented Apr 14, 2025 •

edited

Loading

github-actions bot commented Apr 14, 2025 •

edited

Loading

netlify bot commented Apr 14, 2025 •

edited

Loading

netlify bot commented Apr 14, 2025 •

edited

Loading

netlify bot commented Apr 14, 2025 •

edited

Loading