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。

sql
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;

预期输出

text
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) 这对组合不存在,因此复合外键必须拒绝写入。

sql
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');

预期输出

text
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。

sql
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
);

预期输出

text
ALTER TABLE
CREATE POLICY

USING 控制哪些现有行可见,WITH CHECK 控制新行或更新后的行能否属于当前租户。应用仍应显式写 tenant_id,因为显式字段更便于审计、批量导入和排障;不要把来自客户端的租户编号直接当作可信上下文。

公共字典、套餐模板等全局数据若确实不属于任何单一租户,建立独立表通常最清晰。统一 tenant_id 的真正价值,是让约束、索引、RLS 策略和排障查询都围绕同一份租户语义工作,而不是在每张表里重新解释一次“租户是谁”。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

统一 tenant_id 数据约定

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通