53300 too_many_connections

速览 {#at-a-glance}

53300 是 PostgreSQL 类别 53 insufficient_resources 中的 too_many_connections 条件。新后端因为某个连接容量限制已经达到而无法接纳时，会产生这个代码。代表性案例把一个角色的连接数限制设为 1，再为该角色打开第二个会话。

这是连接启动阶段的失败。被拒绝的会话没有打开 SQL 事务。最终运行中，psycopg 返回了启动异常文本，但暴露的 sqlstate 为 None；PostgreSQL collector 记录了服务器实际发送的 FATAL SQLSTATE 53300。诊断连接池或认证网关时必须分开记录这两种观察。

案例 role_connection_limit 在 PostgreSQL 18.6 和隔离的 PostgreSQL 10.21 目标上均通过。run ID 和逐案例断言保存在公开证据 JSON中。

含义与触发路径 {#meaning}

后端启动时，PostgreSQL 在认证角色后检查该角色的 rolconnlimit。对于连接限制为非负数且不是超级用户的角色，如果连接数超过限制，服务器会使用 ERRCODE_TOO_MANY_CONNECTIONS 报告 FATAL，主报文为 too many connections for role "%s"。源码注释说明并发启动可能竞争，因此角色计数的限制检查是近似的。

同一个 SQLSTATE 也可能表示其他容量路径，例如服务器范围的客户端限制。本页的角色限制案例不能说明每一次 53300 的根因；应结合主报文、collector 字段，以及角色、数据库和服务器配置来分类。

失败发生在 SQL 协议进入事务之前，因此被拒绝的会话没有 INERROR 或 IDLE 这样的事务状态。仍保持打开的管理连接或池连接可以调整限制，再用新的会话证明恢复。

报文与诊断 {#messages}

下面的可执行摘录与 runner 使用相同的角色限制 SQL。隔离运行中 limited_user 会替换成临时角色。第二个连接是独立的客户端启动操作，因此在 SQL 语句之间说明，而不是伪造一条 SQL 来代表它。

ALTER ROLE limited_user CONNECTION LIMIT 1;
-- 保持一个 limited_user 会话处于打开状态。
-- 再以 limited_user 打开第二个会话：启动阶段返回 FATAL 53300。
ALTER ROLE limited_user CONNECTION LIMIT -1;
SELECT 1;

最新目标的 collector 记录形状为：

SQLSTATE: 53300                 # csvlog/jsonlog sql_state_code
severity: FATAL
message_primary: too many connections for role "<generated-role>"
source: miscinit.c / InitializeSessionUserId / line 880
driver startup sqlstate: null
transaction: none opened
repair: reset CONNECTION LIMIT; fresh role connection SELECT 1 -> 1

PostgreSQL 10.21 的 collector 产生相同的报文和 SQLSTATE，源码位置为 miscinit.c:575。两个目标都在恢复限制后成功建立已知角色的新连接。上面的角色名和端口是运行时生成值；collector 的 sql_state_code 才是服务器证据。具体驱动在启动错误上可能不提供 SQLSTATE 属性。

诊断 {#diagnosis}

记录不含密码的连接参数、角色和数据库、服务器版本、启动异常原文，以及按时间、用户和连接来源关联的 collector 记录。检查 pg_roles.rolconnlimit、数据库和服务器连接配置以及当前后端数量。连接池可能耗尽角色限制，而服务器仍有全局容量。

角色计数在突发并发启动下应当作为容量观察，而非精确的接纳证明；PostgreSQL 已在源码中说明这一检查是近似的。先根据主报文定位限制，再决定调整哪个配置，并保留管理通道用于恢复。

不要对被拒绝的会话执行事务清理命令，它从未进入可用的 SQL 事务。仍存活的所有者或管理连接可以恢复配置；有意义的修复断言是受影响角色建立新的连接并执行真实查询。

处理与修复 {#response}

• 限制连接池大小和并发连接创建，避免角色连接数反复耗尽。
• 检查内存、工作负载和接纳策略后，再决定是否提高角色、数据库或服务器容量。
• 为恢复保留管理容量和受控的管理连接；不要仅为绕过限制而授予超级用户权限。
• 修改限制后，用新连接执行无害查询。清理池状态和陈旧会话，再重试应用工作。

代表性修复恢复了临时角色的限制，建立了新的角色连接，并观察到 SELECT 1 返回 1。这证明了角色限制路径的恢复，不能替代对其他数据库级或服务器级容量故障的验证。

版本与边界 {#versions}

目录在 PostgreSQL 7.4 的锁定定义中已观察到 53300，并持续到 8.4.22 的 pre-9.0 定义；随后在列出的所有正式快照直到 PostgreSQL 18.6 以及 PostgreSQL 19 Beta 3 预览中存在。这是 definition_only 的存在边界，不是确切实现引入版本或运行时使用断言。9.0 头文件和 9.1 文本定义之间的类别标题变化已记录在目录中；它不是该条件实现发生变化的断言。

角色限制案例在 PostgreSQL 18.6 和 10.21 上通过。源码行号不同，驱动与 collector 的差异也是实测边界。数据库级、服务器级容量路径、连接池行为和操作系统资源耗尽需要独立证据。

相关 {#related}

28P01 — invalid_password 是另一个没有 SQL 事务的连接启动失败。57014 — query_canceled 是会话建立后发生的语句中断。42P01 — undefined_table 是连接建立后的 SQL 名称解析错误。

来源 {#sources}

结构化证据记录在公开证据 JSON中。源码记录固定到 PostgreSQL commit 724edf9bde9d356724ad384a2e196edc3c9f80f7；运行记录保留 collector 输出、驱动观察、两个目标 ID 和结构化观察。

• src.errcodes.18.6 — errcodes.txt
• src.miscinit.18.6 — miscinit.c
• src.backend-startup.18.6 — backend_startup.c
• doc.protocol.18 — 错误和通知消息字段
• Runtime：latest 与 pg10 均为 53300-registry-final-20260909，结构化观察见公开证据 JSON

来源

• 核验材料 verify/cases/53300/cases.json 631e5ca3
• 核验材料 doc/src/sgml/protocol.sgml PG18-docs 724edf9bd 745339e0
• 核验材料 sources/manifest.lock.json 1727a275
• 核验材料 verify/cases/53300/snippets.json a83d7409
• 核验材料 src/backend/tcop/backend_startup.c 第 340–344 行 REL_18_6 724edf9bd 5516f3d6
• 核验材料 src/backend/utils/errcodes.txt REL_18_6 724edf9bd 6e8de346
• 核验材料 src/backend/utils/init/miscinit.c 第 868–880 行 REL_18_6 724edf9bd 54bdb859