PostgreSQL 行级安全(RLS):把租户隔离交给数据库
做过多租户 SaaS 的人,大概都有过这种担心:所有表都有一列 tenant_id,每条查询都得带上 WHERE tenant_id = ?。几百条查询里,只要有一条漏了,A 公司就能看到 B 公司的数据。
常见的做法是在应用层兜底:ORM 里加一个全局过滤器,或者每个 Repository 方法都强制传租户 ID。这些办法有效,但它们都依赖“所有访问数据库的代码都走这一层”。报表脚本、后台任务、某个同事临时写的原生 SQL、以后接进来的 Agent,都可能绕过去。
PostgreSQL 从 9.5(2016 年 1 月发布)开始提供行级安全(Row-Level Security,下文简称 RLS)1。它的思路很直接:既然每条查询都要带同一个过滤条件,那就把这个条件写在表上,由数据库在每次查询时自动加进去。应用代码忘了写,数据库也不会忘。
这篇从最小的例子开始,再讲策略到底怎么生效、怎么告诉数据库“当前是哪个租户”、哪些情况会绕过 RLS,以及它对性能的影响。文中的 SQL 都在 PostgreSQL 16 上跑过,输出是实际结果。
一分钟上手
先建一张多租户的表。这里用两个角色:app_owner 是表的所有者,跑迁移用;app_user 是应用连接数据库时用的角色。这个区分后面会讲到为什么重要。
CREATE TABLE projects (
id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
tenant_id bigint NOT NULL REFERENCES tenants(id),
name text NOT NULL
);
CREATE INDEX ON projects (tenant_id);
INSERT INTO projects (tenant_id, name)
VALUES (1, '官网'), (1, 'App'), (2, '内部系统');
GRANT SELECT, INSERT, UPDATE, DELETE ON projects TO app_user;
然后打开 RLS:
ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
这时候用 app_user 查询,会发现一行都看不到:
app_user=> SELECT count(*) FROM projects;
count
-------
0
这是 RLS 的第一个规则:表上开了 RLS 但没有任何策略时,默认拒绝,所有行都不可见,也不能修改2。所以打开 RLS 本身是安全的,最坏的情况是查不到数据,而不是查到别人的数据。
接着加一条策略,让每个连接只能看到“当前租户”的行:
CREATE POLICY tenant_isolation ON projects
USING (tenant_id = current_setting('app.tenant_id')::bigint)
WITH CHECK (tenant_id = current_setting('app.tenant_id')::bigint);
app.tenant_id 是一个自定义的会话变量,应用在每个事务开始时设置它:
app_user=> BEGIN;
app_user=> SELECT set_config('app.tenant_id', '1', true);
app_user=> SELECT * FROM projects;
id | tenant_id | name
----+-----------+------
1 | 1 | 官网
2 | 1 | App
app_user=> INSERT INTO projects (tenant_id, name) VALUES (2, '偷塞');
ERROR: new row violates row-level security policy for table "projects"
查询里没写任何 WHERE tenant_id,结果却只有租户 1 的数据;想往租户 2 里插数据,直接报错。这就是 RLS 的全部核心用法,剩下的内容都是在讲它的细节和坑。
策略是怎么生效的
USING 和 WITH CHECK
一条策略有两个表达式,分别管两件事:
USING管“已有的行能不能被看到”。它作用于SELECT、UPDATE、DELETE读到的行,不满足条件的行会被静默过滤,就像它们不存在一样,不会报错;WITH CHECK管“新写入的行合不合法”。它作用于INSERT和UPDATE之后的新行,不满足条件会直接报错3。
如果只写了 USING 没写 WITH CHECK,PostgreSQL 会把 USING 也拿来当 WITH CHECK 用。不过我建议两个都显式写出来,读的人一眼就能看懂。
“静默过滤”这一点要特别留意。用租户 2 的身份去改租户 1 的数据:
app_user=> SET LOCAL app.tenant_id = '2';
app_user=> UPDATE projects SET name = 'x' WHERE tenant_id = 1;
UPDATE 0
app_user=> UPDATE projects SET tenant_id = 1 WHERE name = '内部系统';
ERROR: new row violates row-level security policy for table "projects"
第一条 UPDATE 没有报错,只是影响了 0 行,因为租户 1 的行对它来说根本不存在。第二条想把自己的行“挪”到租户 1,被 WITH CHECK 拦了下来。也就是说,越权读和越权改不会有错误提示,只有越权写入新值才会报错。如果你的业务代码依赖“更新了几行”来判断成功与否,要记得这一点。
数据库替你加了一个 WHERE
从执行计划可以看得更清楚。策略的条件被直接并进了查询的过滤条件,还用上了 tenant_id 上的索引:
app_user=> EXPLAIN (COSTS OFF) SELECT * FROM projects WHERE name = '官网';
Bitmap Heap Scan on projects
Recheck Cond: (tenant_id = (current_setting('app.tenant_id'))::bigint)
Filter: ((NOT archived) AND (name = '官网'::text))
-> Bitmap Index Scan on projects_tenant_id_idx
Index Cond: (tenant_id = (current_setting('app.tenant_id'))::bigint)
按命令区分,以及策略之间怎么组合
策略可以只针对某一类命令(FOR SELECT / INSERT / UPDATE / DELETE),不写就是 FOR ALL。一张表上可以有多条策略,组合规则是3:
- PERMISSIVE(默认):多条之间用
OR组合,满足任意一条就放行。适合“本租户的行,或者公开的行”这类“多种途径都能看到”的规则; - RESTRICTIVE:多条之间用
AND组合,并且和 permissive 的结果再取AND。适合“无论如何都必须满足”的硬性条件。
上面执行计划里的 NOT archived,就来自我加的一条 restrictive 策略,用来隐藏已归档的项目:
CREATE POLICY hide_archived ON projects
AS RESTRICTIVE FOR SELECT
USING (NOT archived);
要注意,只有 restrictive 策略、没有 permissive 策略时,所有行都不可见。restrictive 只能在 permissive 放行的范围里再收紧,不能单独放行。
UPDATE 需要 SELECT 策略
这是一个很容易踩的坑。下面这张表只有一条 FOR UPDATE 策略:
CREATE POLICY upd ON notes FOR UPDATE USING (owner = current_user);
用户去改自己的笔记:
app_user=> UPDATE notes SET body = 'A' WHERE id = 1;
UPDATE 0
app_user=> UPDATE notes SET body = 'B';
UPDATE 1
带 WHERE 的反而改不了,不带 WHERE 的却改成功了。原因是带 WHERE(或 RETURNING)的 UPDATE 需要先“读”已有的行,所以 SELECT 策略也会生效,而这张表没有 SELECT 策略,默认拒绝3。补上一条 FOR SELECT 策略后,第一条语句就正常了。实际业务里几乎所有 UPDATE 和 DELETE 都带 WHERE,所以按命令拆策略时,别忘了 SELECT。多租户隔离这种场景,直接用 FOR ALL 的一条策略最省心。
怎么告诉数据库“我是谁”
策略里总要引用“当前是谁”。有两种主流做法。
做法一:每个用户一个数据库角色
策略写成 owner = current_user,每个终端用户对应一个 PostgreSQL 角色。这种方式最“正统”,身份由数据库自己认证,应用没办法伪造。AWS 那篇关于 RLS 多租户的文章,主例子用的就是这种方式4。
缺点也很明显:角色要随着租户或用户一起创建和删除,连接池按角色分开,几万个用户就是几万个角色。它比较适合租户数量少、每个租户有独立连接的场景。
做法二:会话变量
更常见的是上面例子里的做法:应用用同一个角色连接,在事务开始时把当前租户写进一个自定义变量,策略用 current_setting() 读取。Supabase 的 auth.uid() 本质上也是这个思路,只不过变量里放的是从 JWT 解出来的用户信息5。
这种做法的前提是:设置变量的那段代码必须可信。数据库只认变量,不认是谁设置的。如果攻击者能执行任意 SQL,自己 SET app.tenant_id = '2' 就能切换租户。所以会话变量方案防的是“应用代码写漏了”,不是“攻击者拿到了数据库连接”。
设置变量时,有三个细节值得注意。
第一,一定要用事务级别的设置。 set_config(name, value, true) 的第三个参数 is_local 为 true 时,设置只在当前事务内有效;等价的写法是 SET LOCAL6。如果用了会话级的 SET,再遇上连接池,后果是这样的:
-- 请求 A:用会话级 SET
app_user=> SET app.tenant_id = '1';
app_user=> SELECT count(*) FROM projects;
1
-- 请求 B 复用了同一个连接,但忘了设置租户
app_user=> SELECT count(*) FROM projects;
1
请求 B 什么都没设,却继承了上一个请求的租户身份。用 SET LOCAL 的话,事务一结束设置就消失了,请求 B 只会看到 0 行。PgBouncer 的事务池模式本身也不支持会话级的 SET,文档里写得很明确7,AWS 那篇文章也专门提醒了会话变量和服务端连接池的兼容问题4。事务级的设置跟着事务走,在事务池模式下也是安全的。
第二,处理“没设置”的情况。 current_setting('app.tenant_id') 在变量从未设置过时会直接报错;第二个参数传 true(missing_ok)则返回 NULL6。但这里还有一个我实测才发现的坑:同一个连接上一旦设置过这个变量,事务结束后它不会变回“不存在”,而是变成空字符串。
app_user=> BEGIN; SELECT set_config('app.tenant_id', '1', true); ROLLBACK;
app_user=> SELECT current_setting('app.tenant_id', true) = '' AS is_empty;
is_empty
----------
t
app_user=> SELECT ''::bigint;
ERROR: invalid input syntax for type bigint: ""
所以只加 missing_ok 还不够,复用的连接上会出现 ''::bigint 的类型转换错误。更稳妥的写法是用 nullif 把空字符串也变成 NULL:
CREATE POLICY tenant_isolation ON projects
USING (tenant_id = nullif(current_setting('app.tenant_id', true), '')::bigint)
WITH CHECK (tenant_id = nullif(current_setting('app.tenant_id', true), '')::bigint);
tenant_id = NULL 的结果是 NULL,不算满足条件,没设置租户时就是一行都看不到,正好是我们想要的“默认拒绝”。
第三,把这段逻辑包成一个函数。 每条策略都写一遍 nullif(current_setting(...)) 很啰嗦,也容易写错。可以定义一个 STABLE 的 SQL 函数:
CREATE FUNCTION app_tenant_id() RETURNS bigint
LANGUAGE sql STABLE
AS $$ SELECT nullif(current_setting('app.tenant_id', true), '')::bigint $$;
策略就可以写成 USING (tenant_id = app_tenant_id())。性能一节还会回到这个函数。
谁会绕过 RLS
RLS 最容易给人一种虚假的安全感:策略写好了,以为万事大吉,结果查询走的是一条根本不经过策略的路。下面这些路径,每一条都值得检查一遍。
- 超级用户:永远绕过 RLS2。应用绝不能用
postgres这样的超级用户连接数据库。 - 带
BYPASSRLS属性的角色:同样绕过所有策略。这个属性适合给备份或运维角色,不能给应用角色。 - 表的所有者:默认也绕过 RLS。这是最常见的坑,很多项目的应用角色恰好就是建表的那个角色。在我的例子里,
app_owner查询能看到全部 3 行。解决办法有两个:让应用用一个不拥有表的角色连接(推荐),或者对表执行ALTER TABLE ... FORCE ROW LEVEL SECURITY,让所有者也受策略约束2。 - 视图:视图默认用视图所有者的权限去访问底层的表。如果视图是表的所有者建的,通过视图查询就会绕过 RLS。实测中,同一个租户直接查表看到 2 行,通过普通视图查却看到了 3 行。PostgreSQL 15 开始可以给视图加上
security_invoker = true,让它用调用者的身份检查权限和策略89,加上之后通过视图也只能看到 2 行。 SECURITY DEFINER函数:这类函数以函数所有者的身份执行,如果所有者是表的所有者,函数内的查询同样不受 RLS 约束。有时候这是故意的(比如在策略里查一张受保护的成员表),但要清楚自己在做什么,并且给这类函数固定search_path10。- 唯一约束、主键和外键检查:引用完整性检查总是绕过 RLS2。比如
name上有一个全局唯一约束,租户 2 插入一个名为“官网”的项目,会收到duplicate key value violates unique constraint的错误,由此就能推断出别的租户有一个叫“官网”的项目。官方文档把这称为“隐蔽信道”(covert channel)。对多租户表来说,唯一约束一般都应该带上tenant_id,比如UNIQUE (tenant_id, name)。 row_security参数和备份:普通角色把row_security设为off并不能绕过策略,而是会在查询受策略影响时直接报错query would be affected by row-level security policy。pg_dump默认就是这样设置的,这样可以避免备份“悄悄地”只导出了一部分数据11。所以负责备份的角色需要BYPASSRLS或者是超级用户。
把这些合起来,一个比较稳妥的角色划分是:
| 角色 | 用途 | 拥有表 | BYPASSRLS |
|---|---|---|---|
app_owner |
跑迁移、建表、建策略 | 是 | 否 |
app_user |
应用日常连接 | 否 | 否 |
app_admin |
运营后台、跨租户报表 | 否 | 视情况,最好用单独的策略 |
backup |
备份 | 否 | 是 |
上线前可以用一条查询,列出 public 下所有带 tenant_id 列、却没有打开 RLS 的表:
SELECT c.relname
FROM pg_class c
JOIN pg_namespace n ON n.oid = c.relnamespace
JOIN pg_attribute a ON a.attrelid = c.oid AND a.attname = 'tenant_id'
WHERE n.nspname = 'public' AND c.relkind = 'r' AND NOT c.relrowsecurity;
这条查询很适合放进 CI,新加一张表忘了开 RLS 时能第一时间发现。
性能:大部分时候没问题,但要注意两件事
从前面的执行计划可以看出,RLS 的开销本质上就是“多了一个 WHERE 条件”。只要这个条件能走索引,开销基本可以忽略。需要注意的是下面两件事。
一是给策略里用到的列建索引。 这一点很朴素,但最常被忽略。tenant_id 没有索引时,每条查询都会变成全表扫描。Supabase 的文档把它列为 RLS 性能优化的第一条5。多租户表的复合索引通常也应该把 tenant_id 放在第一列。
二是避免函数被逐行调用。 如果策略里调用的函数没办法被规划器内联(比如用 PL/pgSQL 写的),而这一列又没有索引可用,函数就会对每一行都执行一次。一个常用的技巧是把函数调用包进一个子查询:(SELECT app_tenant_id())。这样规划器会把它当作 InitPlan,整条语句只算一次5。
我在一张 100 万行的表上测了一下,策略条件是 owner_id = 函数(),函数用 PL/pgSQL 写成:
| 写法 | 执行计划 | 耗时 |
|---|---|---|
owner_id = f(),无索引 |
Seq Scan,每行调用一次 f() |
约 340 ms |
owner_id = (SELECT f()),无索引 |
Seq Scan,f() 只算一次 |
约 50 ms |
owner_id = (SELECT f()),有索引 |
Index Only Scan | 0.14 ms |
包一层子查询带来了大约 7 倍的提升,而加上索引又快了两个数量级。所以真正的优先级是:先保证有索引,再考虑函数调用的写法。另外要注意,这个技巧只适用于结果不随行变化的函数,像“当前用户 ID”这种整条语句内不变的值才可以这么写。
还有一个比较隐蔽的点是 LEAKPROOF。为了防止通过函数的报错信息或副作用泄露被策略过滤掉的行,规划器默认不会把用户查询里的条件提前到策略条件之前执行,除非条件里用的函数和运算符被标记为 LEAKPROOF10。内置的大部分比较运算符都是 leakproof 的,一般不会遇到问题;但如果你在查询里用了自定义函数,发现开了 RLS 之后某个索引用不上了,可以往这个方向排查。
在应用里接上
以 Python 的 FastAPI 加 SQLAlchemy 为例,关键是让“设置租户”和“执行业务查询”处在同一个事务里。思路是写一个依赖项,在每个请求开始时开启事务并设置变量:
from fastapi import Depends, Request
from sqlalchemy import text
from sqlalchemy.ext.asyncio import AsyncSession
async def get_tenant_session(
request: Request,
session: AsyncSession = Depends(get_session),
):
tenant_id = request.state.tenant_id # 由认证中间件从 JWT 中解出
async with session.begin():
await session.execute(
text("SELECT set_config('app.tenant_id', :tid, true)"),
{"tid": str(tenant_id)},
)
yield session
有几点需要注意:
- 用
set_config(..., true)而不是拼接SET LOCAL app.tenant_id = ...,因为SET语句不支持参数绑定,拼接字符串有注入风险; - 租户 ID 必须来自已经验证过的身份(比如签名过的 JWT),不能直接读请求参数;
- 后台任务、定时脚本也要走同样的路径设置租户,不要为了方便给它们一个
BYPASSRLS的角色。
怎么测试 RLS
RLS 的测试有一个原则:一定要用应用角色去测。用超级用户或表的所有者跑测试,所有策略都会被绕过,测试永远是绿的。
我一般会写三类用例:
- 隔离:以租户 A 的身份插入数据,再以租户 B 的身份查询,断言结果为空;
- 写入拦截:以租户 A 的身份插入一条
tenant_id = B的数据,断言报错; - 未设置:不设置
app.tenant_id直接查询,断言返回 0 行而不是报错或返回全部。
加上前面那条“带 tenant_id 却没开 RLS 的表”的检查,基本就能覆盖最常见的回归问题了。
什么时候不适合用 RLS
RLS 不是万能的,下面几种情况我会慎重考虑:
- 租户之间需要物理隔离:比如合规要求每个客户的数据存在独立的库里,那就该用独立的数据库或 schema,RLS 解决不了这个问题;
- 权限逻辑非常复杂:比如依赖多层组织结构、动态共享、字段级权限。这些逻辑都塞进 SQL 策略里,会变得很难读、很难测,也很难排查性能问题。一种折中是用 RLS 只做租户这一层硬隔离,更细的权限留在应用层;
- 大量跨租户的分析查询:这类查询更适合放到数仓或只读副本上,用专门的角色来跑。
小结
- RLS 把过滤条件放进了数据库:开启后默认拒绝,策略条件在规划阶段被并进每一条查询;
USING管读,WITH CHECK管写:越权读和越权改是静默的 0 行,只有越权写入新值才会报错;- permissive 用 OR,restrictive 用 AND,只有 restrictive 时什么都看不到;带
WHERE的UPDATE还需要 SELECT 策略; - 会话变量用事务级设置:
set_config(..., true)或SET LOCAL,并用nullif(current_setting(..., true), '')处理“没设置”和“空字符串”两种情况; - 检查所有绕过路径:超级用户、
BYPASSRLS、表所有者、视图、SECURITY DEFINER函数和唯一约束,应用角色不应该拥有表; - 性能的关键是索引,其次是用
(SELECT f())避免函数被逐行调用; - 用应用角色测试,并在 CI 里检查有没有忘了开 RLS 的表。
RLS 不能替代应用层的权限设计,但它能提供一个很重要的保证:就算某一处代码写漏了,数据库这一层也不会把别人的数据交出去。
参考文献
- [1]PostgreSQL Global Development Group. Release 9.5. 2016-01-07. ↩
- [2]PostgreSQL Documentation. 5.9. Row Security Policies. ↩
- [3]PostgreSQL Documentation. CREATE POLICY. ↩
- [4]Beardsley M. Multi-tenant data isolation with PostgreSQL Row Level Security. AWS Database Blog, 2020. ↩
- [5]Supabase Docs. Row Level Security. ↩
- [6]PostgreSQL Documentation. 9.28. System Administration Functions(set_config / current_setting). ↩
- [7]PgBouncer. Features(SQL feature map for pooling modes). ↩
- [8]PostgreSQL Documentation. CREATE VIEW(security_invoker). ↩
- [9]PostgreSQL Global Development Group. Release 15. 2022-10-13. ↩
- [10]PostgreSQL Documentation. CREATE FUNCTION(SECURITY DEFINER / LEAKPROOF). ↩
- [11]PostgreSQL Documentation. 20.11. Client Connection Defaults(row_security). ↩