PostgreSQL / 系统课时
统一 tenant_id 数据约定
统一 tenant_id 数据约定
RLS 能否稳定工作,很大程度取决于数据模型是否把租户归属表达得一致。本课建立一套可落地的 tenant_id 约定:统一类型、强制非空、明确写入来源,并用复合外键阻止跨租户关联,从数据层消除“同名字段但语义不同”的隐患。
学习目标
- 为租户私有表确定统一的
tenant_id类型、空值规则和来源。 - 用主键、唯一约束和复合外键保证关联对象属于同一租户。
- 正确处理公共数据,避免用大量
NULL tenant_id把例外混进租户私有模型。
先固定 tenant_id 的语义
推荐把租户主键与所有租户私有表的 tenant_id 统一为同一种类型,例如 uuid。租户私有数据使用 NOT NULL,不要有的表用 uuid、有的表用 bigint,也不要用字符串临时承载外部租户编号。
tenant_id 的值应来自服务端已经认证并解析完成的租户上下文,而不是直接信任请求体中的同名字段。应用可以显式写入该值,再由 RLS 的 WITH CHECK 或数据库约束做第二次校验;这样“身份来源”和“数据归属字段”有清晰边界。
对于真正面向所有租户的公共数据,优先放入独立公共表。把 tenant_id = NULL 同时解释成“公共数据”会迫使几乎所有策略、唯一约束和查询都增加特殊分支,后续很容易出现漏判。
用复合键防止跨租户关联
仅仅给每张表加 tenant_id 还不够。子表如果只按对象 id 建外键,就可能把租户 B 的记录关联到租户 A 的父对象。更稳妥的做法是让租户作用域参与主键或唯一键,并让子表外键同时携带 tenant_id。
CREATE TABLE tenant (
id uuid PRIMARY KEY,
name text NOT NULL
);
CREATE TABLE project (
tenant_id uuid NOT NULL REFERENCES tenant(id),
id uuid NOT NULL,
name text NOT NULL,
PRIMARY KEY (tenant_id, id)
);
CREATE TABLE task (
tenant_id uuid NOT NULL,
id uuid NOT NULL,
project_id uuid NOT NULL,
title text NOT NULL,
PRIMARY KEY (tenant_id, id),
CONSTRAINT task_project_same_tenant_fk
FOREIGN KEY (tenant_id, project_id)
REFERENCES project (tenant_id, id)
);
INSERT INTO tenant (id, name) VALUES
('11111111-1111-1111-1111-111111111111', 'Tenant A'),
('22222222-2222-2222-2222-222222222222', 'Tenant B');
INSERT INTO project (tenant_id, id, name) VALUES
('11111111-1111-1111-1111-111111111111',
'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
'A Project');
INSERT INTO task (tenant_id, id, project_id, title) VALUES
('11111111-1111-1111-1111-111111111111',
'cccccccc-cccc-cccc-cccc-cccccccccccc',
'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
'A Task');
SELECT tenant_id, id, project_id, title
FROM task;预期输出
CREATE TABLE
CREATE TABLE
CREATE TABLE
INSERT 0 2
INSERT 0 1
INSERT 0 1
tenant_id | id | project_id | title
--------------------------------------+--------------------------------------+--------------------------------------+--------
11111111-1111-1111-1111-111111111111 | cccccccc-cccc-cccc-cccc-cccccccccccc | aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa | A Task
(1 row)这套结构让“项目属于哪个租户”和“任务属于哪个租户”使用同一字段表达,索引也天然以租户作为最左侧作用域。是否把 id 设计成全局唯一仍可按业务选择,但租户内关系不要只靠裸 id 维系。
验证数据库会拒绝跨租户关系
现在尝试让租户 B 的任务引用租户 A 的项目。项目 id 确实存在,但 (tenant_id, project_id) 这对组合不存在,因此复合外键必须拒绝写入。
INSERT INTO task (tenant_id, id, project_id, title) VALUES
('22222222-2222-2222-2222-222222222222',
'dddddddd-dddd-dddd-dddd-dddddddddddd',
'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa',
'Invalid cross-tenant task');预期输出
ERROR: insert or update on table "task" violates foreign key constraint "task_project_same_tenant_fk"
DETAIL: Key (tenant_id, project_id)=(22222222-2222-2222-2222-222222222222, aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa) is not present in table "project".这类约束比“应用代码记得检查租户是否一致”更可靠,因为后台脚本、数据修复和新服务都必须经过同一数据库规则。
让 tenant_id 与 RLS 写入检查一致
启用 RLS 后,读取条件和写入条件最好都直接使用同一个 tenant_id 约定。下面是 project 表的策略片段;它假设应用连接不是表所有者、没有 BYPASSRLS,并且服务端已在当前事务中安全设置 app.tenant_id。
ALTER TABLE project ENABLE ROW LEVEL SECURITY;
CREATE POLICY project_tenant_policy
ON project
TO PUBLIC
USING (
tenant_id = current_setting('app.tenant_id', true)::uuid
)
WITH CHECK (
tenant_id = current_setting('app.tenant_id', true)::uuid
);预期输出
ALTER TABLE
CREATE POLICYUSING 控制哪些现有行可见,WITH CHECK 控制新行或更新后的行能否属于当前租户。应用仍应显式写 tenant_id,因为显式字段更便于审计、批量导入和排障;不要把来自客户端的租户编号直接当作可信上下文。
公共字典、套餐模板等全局数据若确实不属于任何单一租户,建立独立表通常最清晰。统一 tenant_id 的真正价值,是让约束、索引、RLS 策略和排障查询都围绕同一份租户语义工作,而不是在每张表里重新解释一次“租户是谁”。