Home

Row Level Security

Secure your data using Postgres Row Level Security.

When you need granular authorization rules, nothing beats Postgres's Row Level Security (RLS).

Row Level Security in Supabase#

RLS is incredibly powerful and flexible, allowing you to write complex SQL rules that fit your unique business needs. RLS can be combined with Supabase Auth for end-to-end user security from the browser to the database.

RLS is a Postgres primitive and can provide "defense in depth" to protect your data from malicious actors even when accessed through 3rd party tooling.

Policies#

Policies are Postgres's rule engine. Policies are easy to understand once you get the hang of them. Each policy is attached to a table, and the policy is executed every time a table is accessed.

You can just think of them as adding a WHERE clause to every query. For example a policy like this ...


_10
create policy "Individuals can view their own todos."
_10
on todos for select
_10
using ( auth.uid() = user_id );

.. would translate to this whenever a user tries to select from the todos table:


_10
select *
_10
from todos
_10
where auth.uid() = todos.user_id;
_10
-- Policy is implicitly added.

Enabling Row Level Security#

You can enable RLS for any table using the enable row level security clause:


_10
alter table "table_name" enable row level security;

Once you have enabled RLS, no data will be accessible via the API when using the public anon key, until you create policies.

Creating Policies#

Policies are simply SQL logic that you attach to a Postgres table. You can attach as many policies as you want to each table.

Supabase provides some helpers that simplify RLS if you're using Supabase Auth. We'll use these helpers to illustrate some basic policies:

SELECT Policies#

You can specify select policies with the using clause.

Let's say you have a table called profiles in the public schema and you want enable read access to everyone.


_15
-- 1. Create table
_15
create table profiles (
_15
id uuid primary key,
_15
user_id references auth.users,
_15
avatar_url text
_15
);
_15
_15
-- 2. Enable RLS
_15
alter table profiles enable row level security;
_15
_15
-- 3. Create Policy
_15
create policy "Public profiles are visible to everyone."
_15
on profiles for select
_15
to anon -- the Postgres Role (recommended)
_15
using ( true ); -- the actual Policy

Alternatively, if you only wanted users to be able to see their own profiles:


_10
create policy "User can see their own profile only."
_10
on profiles
_10
for select using ( auth.uid() = user_id );

INSERT Policies#

You can specify insert policies with the with check clause.

Let's say you have a table called profiles in the public schema and you only want users to be able to create a profile for themselves. In that case, we want to check their User ID matches the value that they are trying to insert:


_15
-- 1. Create table
_15
create table profiles (
_15
id uuid primary key,
_15
user_id references auth.users,
_15
avatar_url text
_15
);
_15
_15
-- 2. Enable RLS
_15
alter table profiles enable row level security;
_15
_15
-- 3. Create Policy
_15
create policy "Users can create a profile."
_15
on profiles for insert
_15
to authenticated -- the Postgres Role (recommended)
_15
with check ( auth.uid() = user_id ); -- the actual Policy

UPDATE Policies#

You can specify update policies with the using clause.

Let's say you have a table called profiles in the public schema and you only want users to be able to update their own profile:


_15
-- 1. Create table
_15
create table profiles (
_15
id uuid primary key,
_15
user_id references auth.users,
_15
avatar_url text
_15
);
_15
_15
-- 2. Enable RLS
_15
alter table profiles enable row level security;
_15
_15
-- 3. Create Policy
_15
create policy "Users can update their own profile."
_15
on profiles for update
_15
to authenticated -- the Postgres Role (recommended)
_15
using ( auth.uid() = user_id ); -- the actual Policy

DELETE Policies#

You can specify delete policies with the using clause.

Let's say you have a table called profiles in the public schema and you only want users to be able to delete their own profile:


_15
-- 1. Create table
_15
create table profiles (
_15
id uuid primary key,
_15
user_id references auth.users,
_15
avatar_url text
_15
);
_15
_15
-- 2. Enable RLS
_15
alter table profiles enable row level security;
_15
_15
-- 3. Create Policy
_15
create policy "Users can delete a profile."
_15
on profiles for delete
_15
to authenticated -- the Postgres Role (recommended)
_15
using ( auth.uid() = user_id ); -- the actual Policy

Bypassing Row Level Security#

You can create Postgres Roles which can bypass Row Level Security using the "bypass RLS" privilege:


_10
grant bypassrls on "table_name" to "role_name";

This can be useful for system-level access. You should never share login credentials for any Postgres Role with this privilege.

RLS Performance Recommendations#

Every authorization system has an impact on performance. While row level security is powerful, the performance impact is important to keep in mind. This is especially true for queries that scan every row in a table - like many select operations, including those using limit, offset, and ordering.

Based on a series of tests, we have a few recommendations for RLS:

Add indexes#

Make sure you've added indexes on any columns used within the Policies which are not already indexed (or primary keys). For a Policy like this:


_10
create policy "rls_test_select" on test_table
_10
to authenticated
_10
using ( auth.uid() = user_id );

You can add an index like:


_10
create index userid
_10
on test_table
_10
using btree (user_id);

Benchmarks

TestBefore (ms)After (ms)% ImprovementChange
test1-indexed171< 0.199.94%
Before:
No index

After:
user_id indexed

Call functions with select#

You can use select statement to improve policies that use functions. For example, instead of this:


_10
create policy "rls_test_select" on test_table
_10
to authenticated
_10
using ( auth.uid() = user_id );

You can do:


_10
create policy "rls_test_select" on test_table
_10
to authenticated
_10
using ( (select auth.uid()) = user_id );

This method works well for JWT functions like auth.uid() and auth.jwt() as well as security definer Functions. Wrapping the function causes an initPlan to be run by the Postgres optimizer, which allows it to "cache" the results per-statement, rather than calling the function on each row.

caution

You can only use this technique if the results of the query or function do not change based on the row data.

Benchmarks

TestBefore (ms)After (ms)% ImprovementChange
test2a-wrappedSQL-uid179994.97%
Before:
auth.uid() = user_id

After:
(select auth.uid()) = user_id
test2b-wrappedSQL-isadmin11,000799.94%
Before:
is_admin() table join

After:
(select is_admin()) table join
test2c-wrappedSQL-two-functions11,0001099.91%
Before:
is_admin() OR auth.uid() = user_id

After:
(select is_admin()) OR (select auth.uid() = user_id)
test2d-wrappedSQL-sd-fun178,0001299.993%
Before:
has_role() = role

After:
(select has_role()) = role
test2e-wrappedSQL-sd-fun-array1730001699.991%
Before:
team_id=any(user_teams())

After:
team_id=any(array(select user_teams()))

Add filters to every query#

Policies are "implicit where clauses", so it's common to run select statements without any filters. This is a bad pattern for performance. Instead of doing this (JS client example):


_10
const { data } = supabase
_10
.from('table')
_10
.select()

You should always add a filter:


_10
const { data } = supabase
_10
.from('table')
_10
.select()
_10
.eq('user_id', userId)

Even though this duplicates the contents of the Policy, Postgres can use the to construct a better query plan.

Benchmarks

TestBefore (ms)After (ms)% ImprovementChange
test3-addfilter171994.74%
Before:
auth.uid() = user_id

After:
add .eq or where on user_id

Use security definer functions#

A "security definer" function runs using the same role that created the function. This means that if you create a role with a superuser (like postgres), then that function will have bypassrls privileges. For example, if you had a policy like this:


_10
create policy "rls_test_select" on test_table
_10
to authenticated
_10
using (
_10
exists (
_10
select 1 from roles_table
_10
where auth.uid() = user_id and role = 'good_role'
_10
)
_10
);

We can instead create a security definer function which can scan roles_table without any RLS penalties:


_18
create function private.has_good_role()
_18
returns boolean
_18
language plpgsql
_18
security definer -- will run as the creator
_18
as $$
_18
begin
_18
return exists (
_18
select 1 from roles_table
_18
where auth.uid() = user_id and role = 'good_role'
_18
)
_18
end;
_18
$$;
_18
_18
-- Update our policy to use this function:
_18
create policy "rls_test_select"
_18
on test_table
_18
to authenticated
_18
using ( private.has_good_role() );

caution

Security-definer functions should never be created in a schema in the "Exposed schemas" inside your API settings`.

Minimize joins#

You can often rewrite your Policies to avoid joins between the source and the target table. Instead, try to organize your policy to fetch all the relevant data from the target table into an array or set, then you can use an IN or ANY operation in your filter.

For example, this is an example of a slow policy which joins the source test_table to the target team_user:


_10
create policy "rls_test_select" on test_table
_10
to authenticated
_10
using (
_10
auth.uid() in (
_10
select user_id
_10
from team_user
_10
where team_user.team_id = team_id -- joins to the source "test_table.team_id"
_10
)
_10
);

We can rewrite this to avoid this join, and instead select the filter criteria into a set:


_10
create policy "rls_test_select" on test_table
_10
to authenticated
_10
using (
_10
team_id in (
_10
select team_id
_10
from team_user
_10
where user_id = auth.uid() -- no join
_10
)
_10
);

In this case you can also consider using a security definer function to bypass RLS on the join table:

note

If the list exceeds 1000 items, a different approach may be needed or you may need to analyze the approach to ensure that the performance is acceptable.

Benchmarks

TestBefore (ms)After (ms)% ImprovementChange
test5-fixed-join9,0002099.78%
Before:
auth.uid() in table join on col

After:
col in table join on auth.uid()

Specify Roles in your Policies#

Always use the Role of inside your policies, specified by the TO operator. For example, instead of this query:


_10
create policy "rls_test_select" on rls_test
_10
using ( auth.uid() = user_id );

Use:


_10
create policy "rls_test_select" on rls_test
_10
to authenticated
_10
using ( auth.uid() = user_id );

This prevents the policy ( auth.uid() = user_id ) from running for any anon users, since the execution stops at the to authenticated step.

Benchmarks

TestBefore (ms)After (ms)% ImprovementChange
test6-To-role170< 0.199.78%
Before:
No TO policy

After:
TO authenticated (anon accessing)
© Supabase Inc—ContributingAuthor StyleguideOpen SourceSupaSquad