postgres_lsp 安全规则实战:用 disallowUniqueConstraint 规避 UNIQUE 约束的 ACCESS EXCLUSIVE 锁
postgres_lsp 安全规则实战:用 disallowUniqueConstraint 规避 UNIQUE 约束的 ACCESS EXCLUSIVE 锁
本篇文章聚焦 postgres_lsp 项目中 lint/safety 安全规则族下的 disallowUniqueConstraint 规则,讲解它为什么禁止直接通过 ALTER TABLE ... ADD CONSTRAINT ... UNIQUE 添加唯一约束、规则的诊断行为与源码判定逻辑,以及如何在 postgres-language-server.jsonc 中开启该规则并落地"先并发建索引、再挂约束"的安全迁移方案。读完本文,你将能够在自己的数据库迁移与 CI 检查流程中准确启用并解释该规则。
规则速览:诊断类别、版本与来源
| 属性 | 值 |
|---|---|
| 诊断类别 | lint/safety/disallowUniqueConstraint |
| 引入版本 | vnext(尚未随稳定版本发布) |
| 默认严重级别 | Error |
| 是否默认推荐 | 否(recommended: false) |
| 规则来源 | 受 squawk/disallow-unique-constraint 启发 |
规则在源码中的完整定义位于 crates/pgls_analyser/src/lint/safety/disallow_unique_constraint.rs,通过 declare_lint_rule! 宏声明,其中明确标注了版本号 "next"、严重级别 Severity::Error、推荐状态 recommended: false,以及来源 RuleSource::Squawk("disallow-unique-constraint")。该规则的诊断类别同时登记在 crates/pgls_diagnostics_categories/src/categories.rs(第 45 行),并与文档站点 URL 建立了映射关系;规则索引可见于 docs/reference/rules.md(第 44 行)。
规则要解决的问题:UNIQUE 约束背后的 ACCESS EXCLUSIVE 锁
disallowUniqueConstraint 规则的官方描述只有一句话,但背后是 PostgreSQL 运维中一个重要的锁机制问题:
Disallow adding a UNIQUE constraint without using an existing index.
直接执行下面这类语句添加 UNIQUE 约束时,PostgreSQL 会在表上获取 ACCESS EXCLUSIVE 锁:
ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);
ACCESS EXCLUSIVE 是 PostgreSQL 锁级别中最高的锁,它与任何其他锁都不兼容,一旦持有该锁:
- 阻塞该表上的所有读操作(
SELECT); - 阻塞该表上的所有写操作(
INSERT/UPDATE/DELETE); - 对于被高频访问的在线业务表,这意味着一次 DDL 就会造成一段不可接受的业务中断窗口。
因此该规则给出的替代方案是:先在后台用 CREATE UNIQUE INDEX CONCURRENTLY 并发构建唯一索引(不阻塞读写),再把约束挂载到既有索引之上,从而把锁竞争窗口压缩到最小。这也是规则提示(note)所强调的:
Create a unique index CONCURRENTLY and then add the constraint using that index.
触发诊断的两种 SQL 形态
规则的测试样例与文档示例一致,它能够识别两种会触发诊断的写法:
形态一:ALTER TABLE ... ADD CONSTRAINT ... UNIQUE (...)
ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);
此时 linter 输出的诊断信息如下:
code-block.sql:1:1 lint/safety/disallowUniqueConstraint ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
× Adding a UNIQUE constraint requires an ACCESS EXCLUSIVE lock.
> 1 │ ALTER TABLE table_name ADD CONSTRAINT field_name_constraint UNIQUE (field_name);
│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2 │
i Create a unique index CONCURRENTLY and then add the constraint using that index.
形态二:在 ALTER TABLE ... ADD COLUMN 中内联声明 UNIQUE
ALTER TABLE foo ADD COLUMN bar text UNIQUE;
这种写法等价于在新增列的同时隐式创建一个 UNIQUE 约束,同样会触发诊断:
code-block.sql:1:1 lint/safety/disallowUniqueConstraint ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
× Adding a UNIQUE constraint requires an ACCESS EXCLUSIVE lock.
> 1 │ ALTER TABLE foo ADD COLUMN bar text UNIQUE;
│ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
2 │
i Create a unique index CONCURRENTLY and then add the constraint using that index.
合法写法:先并发建索引,再挂载约束
满足规则的推荐做法分两步完成:
CREATE UNIQUE INDEX CONCURRENTLY dist_id_temp_idx ON distributors (dist_id);
ALTER TABLE distributors DROP CONSTRAINT distributors_pkey,
ADD CONSTRAINT distributors_pkey PRIMARY KEY USING INDEX dist_id_temp_idx;
- 第一步通过
CREATE UNIQUE INDEX CONCURRENTLY在不阻塞读写的前提下后台构建唯一索引dist_id_temp_idx; - 第二步执行
ALTER TABLE ... ADD CONSTRAINT ... USING INDEX dist_id_temp_idx,让约束直接复用已经构建好的索引,从而避免ALTER TABLE内部再次对全表加 ACCESS EXCLUSIVE 锁进行扫描。
注意文档示例中挂载的是 PRIMARY KEY,但这一"索引复用"机制同样适用于 UNIQUE 约束——ALTER TABLE ... ADD CONSTRAINT ... UNIQUE USING INDEX index_name 正是 PostgreSQL 官方推荐的在线加唯一约束方式。规则源码在判定时检查的是约束类型是否为 ConstrUnique 且没有关联既有索引(constraint.indexname.is_empty()),因此凡是显式通过 USING INDEX 挂载既有索引的写法都不会被该规则报告。
源码级解析:规则是如何判定与豁免的
该规则并非简单地"看到 UNIQUE 就报错",从 crates/pgls_analyser/src/lint/safety/disallow_unique_constraint.rs 的实现可以看出,它做了精细的场景区分:
- 仅作用于
ALTER TABLE语句:规则只对NodeEnum::AlterTableStmt生效,其他语句直接放行。 - 同文件内新建表的豁免:规则会扫描当前文件中此前的语句,如果目标表是在同一个事务/文件内通过
CreateStmt刚创建的(table_created_in_transaction为真),则跳过检查——因为新表上执行的ALTER TABLE不会影响线上流量,不需要强制走并发索引流程。这一逻辑对应源码第 53-66 行的previous_stmts()遍历。 - 逐条扫描
ALTER子命令:通过stmt.cmds遍历所有AlterTableCmd,只关心两类子命令:AtAddConstraint:解析cmd.def中的Constraint节点,当约束类型为ConstrUnique且indexname为空(即没有复用既有索引)时报告诊断;AtAddColumn:解析新增列的ColumnDef,遍历其内联constraints,只要出现ConstrUnique就报告诊断。
也就是说,规则的判定核心是"新增 UNIQUE 约束但未使用既有索引"这一事实,与文档描述完全一致。所有 AST 解析均基于 pgls_query 生成的 PostgreSQL 语法树节点(如 AlterTableStmt、AlterTableCmd、Constraint、ColumnDef 及 AlterTableType::AtAddConstraint / AtAddColumn),因此诸如 ADD COLUMN bar text UNIQUE 这类内联写法也逃不过检测。
如何配置:在 postgres-language-server.jsonc 中开启规则
该规则默认不随推荐集合启用(recommended: false),需要显式在配置文件 postgres-language-server.jsonc 的 linter.rules.safety 段中开启。仓库根目录自带一份示例配置 postgres-language-server.jsonc 可供参考,其配置结构如下:
{
"linter": {
"rules": {
"safety": {
"disallowUniqueConstraint": "error"
}
}
}
}
配置说明:
linter.rules.safety对应lint/safety这一诊断类别下的规则集合;- 取值可为
"error"(报错并影响退出码)、"warn"(仅警告)或"off"(关闭);由于规则默认严重级别就是Severity::Error,显式写成"error"与不写效果一致,但建议显式声明以便团队内可读; - 该规则的选项类型为空(
type Options = ()),没有任何可调参数,配置层面只需控制开关与级别。
规则名在配置层面的解析位于 crates/pgls_configuration/src/linter/rules.rs(第 364 行注册规则名、第 1071 行映射默认严重级别),CLI/服务端通过 crates/pgls_analyser/src/registry.rs 中的规则注册表把名称解析为实际的 DisallowUniqueConstraint 实现。
使用场景与注意事项
- 在线业务表迁移:对生产环境的大表添加唯一约束时,务必先
CREATE UNIQUE INDEX CONCURRENTLY再挂约束,避免长时间阻塞读写——这正是本规则要守住的底线; - 一次性脚本 / 初始化脚本:如果表是在同一个文件中刚
CREATE TABLE创建的,规则会自动豁免(源码中的table_created_in_transaction分支),无需手工关闭规则; - 新建表后的即时约束:对于新建表的场景,直接在
CREATE TABLE中声明列级或表级UNIQUE是合法的,规则只针对ALTER TABLE路径,CREATE TABLE ... UNIQUE不会被报告; - 主键约束:本规则只关心 UNIQUE 约束;主键约束由独立的
addingPrimaryKeyConstraint规则管理(见 docs/reference/rules/adding-primary-key-constraint.md),但"复用并发索引"的迁移手法对两者同样适用。
小结
disallowUniqueConstraint 是 postgres_lsp 安全规则族中针对"在线表加唯一约束"这一高频高风险操作的保护性规则:它把"必须使用既有索引"这一 PostgreSQL 最佳实践固化为可自动检测的诊断,覆盖 ADD CONSTRAINT ... UNIQUE 与 ADD COLUMN ... UNIQUE 两种写法,并智能豁免同文件新建表的场景。在实际落地时,将其与 CREATE UNIQUE INDEX CONCURRENTLY + USING INDEX 的标准迁移流程配合,即可在 CI 阶段提前拦截潜在的表级锁风险,保证数据库变更的可控与平滑。