postgres_lsp 安全规则实战:用 disallowUniqueConstraint 规避 UNIQUE 约束的 ACCESS EXCLUSIVE 锁

原创2026-09-17 20:02:291,955 阅读
文章标签:开发工具数据库CLI

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 的实现可以看出,它做了精细的场景区分:

  1. 仅作用于 ALTER TABLE 语句:规则只对 NodeEnum::AlterTableStmt 生效,其他语句直接放行。
  2. 同文件内新建表的豁免:规则会扫描当前文件中此前的语句,如果目标表是在同一个事务/文件内通过 CreateStmt 刚创建的(table_created_in_transaction 为真),则跳过检查——因为新表上执行的 ALTER TABLE 不会影响线上流量,不需要强制走并发索引流程。这一逻辑对应源码第 53-66 行的 previous_stmts() 遍历。
  3. 逐条扫描 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 阶段提前拦截潜在的表级锁风险,保证数据库变更的可控与平滑。

登录后查看全文
postgres_lsp