↑↓ 选择↵ 打开⌫ 切换范围完整搜索

PG.CENTER 连接 PostgreSQL 文档、百科与生态知识。由 Pigsty 维护。

Wiki / SQLSTATE

53300 — too_many_connections（连接数过多）

连接数达到角色、库或服务器上限，新连接被拒。

英文手册覆盖始于 PostgreSQL 8.1. 来源历史与运行验证各自保留独立版本边界。

当前阅读 PG 18·选择有来源记录的版本

8.18.28.38.49.09.19.29.39.49.59.61011121314151617181920
aliases
未知
class name
Insufficient Resources
condition name
too_many_connections
lang
en
sqlstate
53300

版本定义 PG 18

速览 {#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 和结构化观察。

比较版本

SQLSTATE 证据与已记录的运行版本

cases · role_connection_limit
{
  "assertions": [
    "The new connection receives FATAL SQLSTATE 53300",
    "The existing owner connection can restore the limit and continue"
  ],
  "case_id": "role_connection_limit",
  "cleanup": "Restore the role limit, drop the role, and drop the case schema.",
  "has_snippet": true,
  "position": 0,
  "preconditions": [
    "A disposable login role",
    "The role connection limit is set to one while one session is already connected"
  ],
  "repair": "Pool and bound connections, reserve capacity for administration, and investigate the role/database/server limit that was reached.",
  "trigger": "Open a second connection for that role.",
  "versions": [
    "10",
    "18"
  ]
}
claims · identity.class-and-condition
{
  "claim_id": "identity.class-and-condition",
  "limits": "Directory identity does not identify whether a role, database, or server-wide capacity limit caused an occurrence.",
  "method": "Read the Class 53 section and 53300 row in the frozen errcodes.txt snapshot.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "53300 is the too_many_connections condition in Class 53 insufficient_resources."
}
claims · mechanism.role-connection-limit
{
  "claim_id": "mechanism.role-connection-limit",
  "limits": "This source path is role-specific; other capacity paths can use 53300 with different messages.",
  "method": "Read the role connection-limit branch, explicit ERRCODE_TOO_MANY_CONNECTIONS, message construction, and concurrency comment.",
  "position": 1,
  "runtime": [],
  "sources": [
    "src.miscinit.18.6"
  ],
  "statement": "During backend startup, a non-superuser role whose CountUserBackends result exceeds rolconnlimit receives FATAL SQLSTATE 53300 with too many connections for role \"%s\"; the source documents the count check as approximate under a race."
}
claims · mechanism.server-capacity
{
  "claim_id": "mechanism.server-capacity",
  "limits": "This is a source-confirmed server-wide startup gate; it is not covered by the role-limit runtime case and does not classify database or operating-system resource failures.",
  "method": "Read the CAC_TOOMANY backend-startup branch in the fixed source.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.backend-startup.18.6"
  ],
  "statement": "The server-wide startup capacity gate also reports SQLSTATE 53300 at FATAL with sorry, too many clients already."
}
claims · runtime.driver-collector-boundary
{
  "claim_id": "runtime.driver-collector-boundary",
  "limits": "Driver exposure can vary by client and startup failure; the collector record is the server-side SQLSTATE evidence here.",
  "method": "Compare the driver diagnostic, CSV collector state_code, message, severity, and source location in both final summaries and raw records.",
  "position": 3,
  "runtime": [],
  "sources": [
    "doc.protocol.18",
    "runtime.53300-registry-final-20260909.latest",
    "runtime.53300-registry-final-20260909.pg10"
  ],
  "statement": "For the rejected startup connection, psycopg exposed startup text with sqlstate null while the PostgreSQL collector recorded FATAL SQLSTATE 53300 and the role-limit message on both targets."
}
claims · runtime.capacity-repair
{
  "claim_id": "runtime.capacity-repair",
  "limits": "The repair proves the role-limit path only; it does not prove recovery of another global capacity limit.",
  "method": "Keep one holder session, trigger the second startup, restore the limit through an owner connection, and assert a new role session and query.",
  "position": 4,
  "runtime": [],
  "sources": [
    "case-manifest.53300",
    "snippet-registry.53300.final",
    "runtime.53300-registry-final-20260909.latest",
    "runtime.53300-registry-final-20260909.pg10"
  ],
  "statement": "After resetting the disposable role's connection limit, a fresh connection for that role executed SELECT 1 and returned 1 on PostgreSQL 18.6 and 10.21."
}
claims · versions.catalogue-boundary
{
  "claim_id": "versions.catalogue-boundary",
  "limits": "The first scanned release is a lower bound, not an asserted introduction version.",
  "method": "Read the manifest snapshots and definition references for the code.",
  "position": 5,
  "runtime": [],
  "sources": [
    "manifest.53300"
  ],
  "statement": "The locked catalogue records 53300 in every listed formal snapshot from 9.0.23 through 18.6 and in 19beta3; pre-9.0 history is not scanned."
}
messages · message.server-capacity
{
  "limits": "This template belongs to the server-wide startup gate and is distinct from the role-limit template.",
  "message_id": "message.server-capacity",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.server-capacity",
    "limits": "This template belongs to the server-wide startup gate and is distinct from the role-limit template.",
    "primary_template": "sorry, too many clients already",
    "severity_source": "explicit FATAL",
    "sources": [
      "src.backend-startup.18.6"
    ],
    "sqlstate": "53300"
  },
  "severity": "explicit FATAL",
  "sources": [
    "src.backend-startup.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "sorry, too many clients already",
      "position": 0,
      "role": "",
      "template": "sorry, too many clients already"
    }
  ]
}
messages · message.role-limit
{
  "limits": "The role name is dynamically inserted; database-wide and server-wide capacity branches may use another primary template.",
  "message_id": "message.role-limit",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.role-limit",
    "limits": "The role name is dynamically inserted; database-wide and server-wide capacity branches may use another primary template.",
    "primary_template": "too many connections for role \"%s\"",
    "severity_source": "explicit FATAL",
    "sources": [
      "src.miscinit.18.6"
    ],
    "sqlstate": "53300"
  },
  "severity": "explicit FATAL",
  "sources": [
    "src.miscinit.18.6"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "too many connections for role \" \"",
      "position": 0,
      "role": "",
      "template": "too many connections for role \"%s\""
    }
  ]
}
runtimes · runtime.53300-registry-final-20260909.latest · 18.6 (Homebrew) · passed
{
  "cases": [
    "role_connection_limit"
  ],
  "limits": "",
  "position": 0,
  "raw": {
    "cases": [
      "role_connection_limit"
    ],
    "id": "runtime.53300-registry-final-20260909.latest",
    "observed": {
      "collector_message": "too many connections for role \u003cgenerated-role\u003e",
      "collector_severity": "FATAL",
      "collector_source": "miscinit.c:880",
      "collector_sqlstate": "53300",
      "driver_sqlstate": null,
      "driver_text": "FATAL: too many connections for role \u003cgenerated-role\u003e",
      "restored_query": 1,
      "transaction": "none opened for rejected startup"
    },
    "raw": "verify/results/53300-registry-final-20260909/latest/raw.jsonl",
    "raw_sha256": "5fbcf85150b62d596ca4b2356639fdcd89ca2a910447e2be9029b90de108a635",
    "run_id": "53300-registry-final-20260909",
    "server_version": "18.6 (Homebrew)",
    "server_version_num": 180006,
    "snippet_registry": {
      "path": "verify/cases/53300/snippets.json",
      "sha256": "a83d740917ef53c3bf24494c12fe87f4c9cbb38f1e23c17991f2431ba13fa243"
    },
    "status": "passed",
    "summary": "verify/results/53300-registry-final-20260909/latest/summary.json",
    "summary_sha256": "e5505e6d644d9f68ba723c9af63fe069e69d030d1f554b8e8d37316b441f55a9",
    "target": "latest"
  },
  "run_id": "53300-registry-final-20260909",
  "runtime_id": "runtime.53300-registry-final-20260909.latest",
  "server_version": "18.6 (Homebrew)",
  "status": "passed",
  "target": "latest"
}
runtimes · runtime.53300-registry-final-20260909.pg10 · 10.21 (Debian 10.21-1.pgdg90+1) · passed
{
  "cases": [
    "role_connection_limit"
  ],
  "limits": "",
  "position": 1,
  "raw": {
    "cases": [
      "role_connection_limit"
    ],
    "id": "runtime.53300-registry-final-20260909.pg10",
    "image": "postgres@sha256:b2baf8998630663d21370da06387c950e587071bdd307ee34e661cdcc7442bcc",
    "observed": {
      "collector_message": "too many connections for role \u003cgenerated-role\u003e",
      "collector_severity": "FATAL",
      "collector_source": "miscinit.c:575",
      "collector_sqlstate": "53300",
      "driver_sqlstate": null,
      "driver_text": "FATAL: too many connections for role \u003cgenerated-role\u003e",
      "restored_query": 1,
      "transaction": "none opened for rejected startup"
    },
    "raw": "verify/results/53300-registry-final-20260909/pg10/raw.jsonl",
    "raw_sha256": "b03ea276f638c91efadd0791a9818993fc21620ec27ef643c60b7a9904fac6c3",
    "run_id": "53300-registry-final-20260909",
    "server_version": "10.21 (Debian 10.21-1.pgdg90+1)",
    "server_version_num": 100021,
    "snippet_registry": {
      "path": "verify/cases/53300/snippets.json",
      "sha256": "a83d740917ef53c3bf24494c12fe87f4c9cbb38f1e23c17991f2431ba13fa243"
    },
    "status": "passed",
    "summary": "verify/results/53300-registry-final-20260909/pg10/summary.json",
    "summary_sha256": "2ed0896c1548c0a3115e55381e03b0ccd392abe241552b574c64e88cca052f59",
    "target": "pg10"
  },
  "run_id": "53300-registry-final-20260909",
  "runtime_id": "runtime.53300-registry-final-20260909.pg10",
  "server_version": "10.21 (Debian 10.21-1.pgdg90+1)",
  "status": "passed",
  "target": "pg10"
}
sources · src.errcodes.18.6
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "",
  "location": "lines 407-414",
  "path": "src/backend/utils/errcodes.txt",
  "position": 0,
  "sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
  "source_id": "src.errcodes.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt"
}
sources · src.backend-startup.18.6
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "",
  "location": "lines 340-344",
  "path": "src/backend/tcop/backend_startup.c",
  "position": 1,
  "sha256": "5516f3d6d83ae6fc66ca6bad9a7cea3cd2f8de53f0597c26baa2bd224ac270bb",
  "source_id": "src.backend-startup.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/tcop/backend_startup.c#L340-L344"
}
sources · src.miscinit.18.6
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "",
  "location": "lines 868-880",
  "path": "src/backend/utils/init/miscinit.c",
  "position": 2,
  "sha256": "54bdb859c143a6c70d86067ccf2e124f59aa0852e5705bb653652e41a60af39a",
  "source_id": "src.miscinit.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/init/miscinit.c#L868-L880"
}
sources · doc.protocol.18
{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "",
  "location": "ErrorResponse fields",
  "path": "doc/src/sgml/protocol.sgml",
  "position": 3,
  "sha256": "745339e07ebbc2bb67d98b258e25772ada644ef26011e3cd6b3fcbb435235f89",
  "source_id": "doc.protocol.18",
  "tag": "PG18-docs",
  "url": "https://www.postgresql.org/docs/18/protocol-error-fields.html"
}
sources · manifest.53300
{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "snapshots and definition_blobs entries for the 53300 definition",
  "path": "sources/manifest.lock.json",
  "position": 4,
  "sha256": "1727a275f336988ff96b4f9990a4ca253080f73fc5d316e7def165c8cf3708a8",
  "source_id": "manifest.53300",
  "tag": "",
  "url": "../sources/manifest.lock.json"
}
sources · case-manifest.53300
{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "role_connection_limit",
  "path": "verify/cases/53300/cases.json",
  "position": 5,
  "sha256": "631e5ca3a0056fe00b6d1495ddbe4a7880a5d4c09b1520c2ee972859d9174d4d",
  "source_id": "case-manifest.53300",
  "tag": "",
  "url": "../verify/cases/53300/cases.json"
}
sources · snippet-registry.53300.final
{
  "commit": "",
  "docs_url": "",
  "kind": "local_artifact",
  "location": "role_connection_limit ordered SQL",
  "path": "verify/cases/53300/snippets.json",
  "position": 6,
  "sha256": "a83d740917ef53c3bf24494c12fe87f4c9cbb38f1e23c17991f2431ba13fa243",
  "source_id": "snippet-registry.53300.final",
  "tag": "",
  "url": "../verify/cases/53300/snippets.json"
}

来源引用

完整定义与证据 JSON

定义来源

center · PostgreSQL 18 · english-manuals:ef69e2e58a5dd983283ff6c6091d86a6169973084e94f1cfd1ee1970a7308797

正文语言: zh-Hans · english-manuals:ef69e2e58a5dd983283ff6c6091d86a6169973084e94f1cfd1ee1970a7308797