# 42501 — 权限不足（insufficient_privilege）

> PostgreSQL SQLSTATE 42501（权限不足，insufficient_privilege）的源码证据、诊断与处理参考。
---

# 42501 — 权限不足

## 速览 {#at-a-glance}

SQLSTATE `42501` 是 Class `42` 中的 **insufficient_privilege**。`42501` 表示权限不足。选定的自然路径让另一个角色在只有 schema USAGE、没有 sequence USAGE 时调用 runner 自有序列的 `nextval`，服务器报告 `permission denied for sequence %s`。

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `42501` |
| 条件名 | `insufficient_privilege` |
| 状态 | `有效` |
| 已知存在于 | `7.4` |
| 锁定快照 | `9.0.23, 9.1.24, 9.2.24, 9.3.25, 9.4.26, 9.5.25, 9.6.24, 10.23, 11.22, 12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| 宏 | `ERRCODE_INSUFFICIENT_PRIVILEGE` |
| 别名 | `—` |

<!-- source facts: data/errcodes/42501.json -->
<!-- END SQLSTATE FACTS -->

## 含义 {#meaning}

`42501` 表示权限不足。在选定路径中，`nextval` 进入 `nextval_internal`，先按有效的 `GetUserId()` 检查序列访问权限，再推进序列。schema 的 `USAGE` 只允许受限角色解析该 schema 中的对象，并不会授予本次调用所需的序列权限，因此服务器发出 `ERROR` 主报文 `permission denied for sequence %s`；其中序列名是动态值。

这里的 owner 边界很重要：owner 或管理员连接负责准备一次性 schema 和序列，另一个受限角色连接负责执行 `nextval`。实际修复是由 owner/管理员连接窄授 `GRANT USAGE ON SEQUENCE ...`，再让同一个受限角色重试；这不表示受限角色可以自行给自己授权。

同一 SQLSTATE 还覆盖其他权限边界。通用 ACL 检查器可以报告 `permission denied for relation %s`、`permission denied for schema %s` 或列级形式；只允许 owner 的操作则使用 `must be owner of relation %s` 或相应对象类型。行级安全是执行器的另一层检查：表 ACL 通过时，`INSERT` 或 `UPDATE` 的行仍可能违反策略并报 `new row violates row-level security policy ...`。这些是固定源码确认的 producer 分支，不是选定序列运行的额外观察。

## 诊断 {#diagnosis}

检查 `current_user`、`session_user`、任何 `SET ROLE`、数据库、schema、准确关系或列，以及相应 ACL。把准备/授权连接与探测连接分开：将 `runner_host`、`runner_port`、`runner_db`、`runner_user` 替换为真实一次性目标和 owner/管理员凭据，再用另一个连接以生成的受限角色（例如 `syntax_role`）执行 `nextval`。否则连接池可能让 ACL 变更看起来作用到了另一个 backend。如果主报文点名关系、schema 或列，应检查该对象的权限，而不是假设都是 sequence `USAGE`；`must be owner` 要检查对象 owner 和生效角色；RLS 主报文则要检查适用于该角色的策略 `USING`/`WITH CHECK`。选定的自动提交探测得到 `ERROR` 后同一探测会话仍为 `IDLE`；显式事务则要先按自己的错误状态处理，再继续操作。它不同于 28000 的启动授权失败和 0A000 的功能不支持。

## 处理 {#response}

由 owner/管理员连接只授予准确对象所需的权限（本例为 sequence `USAGE`），或使用应用设计所需的 owner/security-definer 或 RLS 策略。修改 ACL 后在同一个受限角色会话重试 `nextval`，并核对返回值和会话状态。超级用户确实会绕过 ACL，但不要把角色升为超级用户来替代有针对性的最小授权；schema `USAGE`、表权限和序列权限是不同检查。owner-only 失败应使用 owner/迁移角色，或有意识地变更 owner，而不是把 ACL 授权当成 owner 转移。如果涉及角色成员关系或 `SET ROLE`，还要检查实际生效角色。

## 报文 {#messages}

选定序列源码路径以 SQLSTATE `42501` 发出明确的 `ERROR`，主报文为 `permission denied for sequence %s`。`%s` 是解析出的序列关系名；该路径没有 DETAIL 或 HINT。其他固定 ACL 分支使用 `permission denied for relation %s`、`permission denied for schema %s` 和 `permission denied for column "%s" of relation "%s"`；owner-only 检查使用 `must be owner of relation %s` 或相应对象类型。RLS `WITH CHECK` 分支使用 `new row violates row-level security policy ...` 主报文。只有客户端异常而没有针对具体分支的服务器 SQLSTATE 和主报文时，不能据此识别该 `42501` producer。

## 代表案例 {#case}

<!-- BEGIN SQLSTATE SNIPPET: permission_denied_sequence -->

本页使用与运行器注册表相同的语句。owner/管理员连接创建序列并授予 schema `USAGE`；受限角色连接执行两次 `nextval` 探测。执行时，`syntax_schema`、`syntax_role` 等生成名称会替换为一次性实例中的实际值，`runner_host`、`runner_port`、`runner_db`、`runner_user` 等连接占位符也必须替换为真实目标，不能照抄字面值。

```sql
CREATE SEQUENCE syntax_schema.syntax_sequence START WITH 1;
GRANT USAGE ON SCHEMA syntax_schema TO syntax_role;
SELECT nextval('syntax_schema.syntax_sequence');
GRANT USAGE ON SEQUENCE syntax_schema.syntax_sequence TO syntax_role;
SELECT nextval('syntax_schema.syntax_sequence');
```

<!-- END SQLSTATE SNIPPET -->

选定的 18.6 运行记录结构化诊断并通过修复断言；10.21 运行通过同一案例的具体检查。可下载的案例和证据投影分别是 [`42501 案例 JSON`](../../data/cases/42501.json) 和 [`作者证据`](../../data/evidence/42501.json)。运行器清单为 `verify/cases/42501/cases.json`，页面 SQL 会与共享注册表核对。

## 版本 {#versions}

选定的自然运行范围是 PostgreSQL 18.6 与 10.21，不能据此推断所有中间版本的行为。

## 相关 {#related}

- [`28000` — 相关条件](../28000/)
- [`0A000` — 相关条件](../0a000/)
- [`42601` — 语法错误](../42601/)

## 来源 {#sources}

- `src.errcodes.18.6` — fixed `errcodes.txt` definition at commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`; SHA-256 `6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba` ([source](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt)).
- `src.sequence-permission.18.6` — `src/backend/commands/sequence.c` at `REL_18_6` commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`; fixed blob SHA-256 `3e5afe17d5a84862fae502a5481211220368f1d639e9d07ba6f96ee8be92a8d8` ([source](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/commands/sequence.c#L652-L655)).
- `src.sequence-permission.10.23` — `src/backend/commands/sequence.c` at `REL_10_23` commit `02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4`; fixed blob SHA-256 `5510e1266e8d8c548a4318d753392e92e689d348f3353a2aa53d8dea871c44ab` ([source](https://github.com/postgres/postgres/blob/02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4/src/backend/commands/sequence.c#L605-L608)).
- `src.aclcheck-errors.18.6` / `src.aclcheck-errors.10.23` — fixed `src/backend/catalog/aclchk.c` ACL-kind tables map no-privilege and not-owner results to relation/schema/column messages; blob SHA-256 `9700258318959b47c42edb423418fb511dd3a008023e732f601eecf4c80868f8` / `3a4330bd55ea8c0ec12324d7046ec31d64c920f99196235b84612d6cd1a4b26c` ([18.6 source](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/catalog/aclchk.c#L2793-L2795), [10.23 source](https://github.com/postgres/postgres/blob/02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4/src/backend/catalog/aclchk.c#L3301-L3449)).
- `src.rls-errors.18.6` / `src.rls-errors.10.23` — fixed `src/backend/executor/execMain.c` row-level security `WITH CHECK` errors; blob SHA-256 `33b97337fa23a649c5e7a092e1bd405a54e8503529236c62c9d5bb93a1774a8d` / `386d09f7e964ebc426a554cf51ac7cb505c67cc95b971ee7acad1a6e0a9d0c1a` ([18.6 source](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/executor/execMain.c#L2332-L2365), [10.23 source](https://github.com/postgres/postgres/blob/02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4/src/backend/executor/execMain.c#L2188-L2208)).
- `src.calls.REL_18_6` / `src.calls.REL_10_23` — fixed call scans, SHA-256 `9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf` / `00d16d3eb01b71ccf1b245c8f3102f9d0ec9f36fb02777b8dd1b99fcb263040c`.