# 08006 — 连接失败（connection_failure）

> PostgreSQL SQLSTATE 08006（连接失败，connection_failure）的源码证据、诊断与处理参考。
---

# 08006 — 连接失败

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

SQLSTATE `08006` 是 Class `08` 中的 **connection_failure**。`08006` 表示已有连接发生故障。固定路径包括 `postgres_fdw` 的取消/连接丢失处理以及 COPY 失败处理；它们没有一个适用于所有路径的主报文或严重级别，本批也有意不做普通 socket 的伪案例。

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

| 字段 | 值 |
| --- | --- |
| SQLSTATE | `08006` |
| 条件名 | `connection_failure` |
| 状态 | `有效` |
| 已知存在于 | `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_CONNECTION_FAILURE` |
| 别名 | `—` |

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

## 含义 {#meaning}

固定源码路径说明了为什么本类没有统一报文。在 `postgres_fdw` 中，取消请求失败时，在处理已有外部连接的过程中发出 `WARNING`；这是取消路径的诊断，本身不证明客户端会话已经终止。在 COPY 路径中，带有未完成事务的客户端 EOF 以 `ERROR` 报告，而较旧的 COPY-to-stdout 路径在输出连接丢失时以 `FATAL` 报告。严重级别和发生阶段都是含义的一部分，不能把它们合并成“socket 断了”。

`ERROR` 分支若发生在显式事务中，仍连接着的会话可能进入 `INERROR`，调用者应先 `ROLLBACK` 或回到合适的保存点再执行无关 SQL。`FATAL` 分支会结束后端连接，不存在可以发送 `ROLLBACK` 的会话。已经读到 EOF 的客户端也可能根本没有 SQLSTATE。这里的证据确认这些源码分支，但没有声称每次普通网络断开都会发出 08006。

### 分支指引 {#scenarios}

| 固定分支 | 它说明什么 | 首先检查什么 |
| --- | --- | --- |
| `postgres_fdw` 取消 `WARNING` | 已建立的外部连接上，取消请求无法发送或无法读取结果。 | 保留动态 libpq 文本、FDW 操作和本地事务状态；WARNING 本身不说明本地会话已关闭。 |
| COPY 客户端 EOF `ERROR` | 服务器在 COPY 相关连接仍有未完成事务时检测到 EOF。 | 触发该分支的客户端 socket 已经到达 EOF，不能在其上发送 `ROLLBACK` 或复用；应重新连接并核对 COPY 结果。 |
| COPY-to-stdout `FATAL` | 固定的 10.23 路径在 COPY 期间丢失输出连接，并使用 fatal 级别。 | 丢弃后端连接并核对已经发送或接收的数据；不能执行会话级回滚。 |
| 普通客户端 EOF | 对端在固定服务器分支之外消失。 | 结合驱动/socket 和服务器日志；不要仅凭客户端 `null` SQLSTATE 指定 08006。 |

## 诊断 {#diagnosis}

关联后端 PID、操作、服务器日志字段和客户端异常。客户端断 socket 可能得到 `null` SQLSTATE，而服务器端 FDW 或 COPY 路径可能发出带路径特定文本的 08006。决定是否重试前，区分 08001（尚未建立连接）、08007/40003（完成结果不确定）和语句尚未执行成功的普通错误。

要同时检查严重级别和生命周期。`WARNING` 表示 FDW 取消分支中本地会话可能仍然存活；`ERROR` 要检查 `INERROR` 还是 `IDLE`，必要时恢复事务；`FATAL` 表示后端已消失。如果客户端在 ErrorResponse 之前只读到 EOF，没有 SQLSTATE 是线路交换丢失的正常证据，不能据此认定 08006。

## 处理 {#response}

丢弃连接池标记为损坏的连接，核对远端或非幂等操作的结果，并在明确幂等策略后重试完整操作。本页只确认固定源码边界；没有用 `RAISE`、超时或普通断 socket 冒充实测 08006。

对另一个仍保持连接的 `ERROR` 情形，应先回滚失败的显式事务（或回滚到围绕该操作有意建立的保存点），再决定能否重试完整操作。这个一般事务规则不能证明 COPY 客户端 EOF socket 可复用：源码分支已经检测到该客户端连接的 EOF。`FATAL` 或已经丢失的 socket 则要建立新会话，并在任何重放前核对结果。自动提交不会让远端或 COPY 操作自动具备幂等性，它只改变本地事务边界。

## 报文 {#messages}

固定分支包含以下不同诊断：

- `postgres_fdw` 取消路径的 `WARNING`：`could not send cancel request: %s`，其中 libpq 错误文本是动态值。
- 同一 FDW 路径的 `WARNING`：`could not get result of cancel request: %s`，返回的连接错误文本是动态值。
- 固定 10.23 COPY 路径的 `FATAL`：`connection lost during COPY to stdout`。
- 固定 18.6/10.23 COPY 客户端 EOF 路径的 `ERROR`：`unexpected EOF on client connection with an open transaction`。

证据将这些变体分开记录；普通客户端断 socket 得到的 `null` SQLSTATE 不能被提升为 08006。

即使报文都提到连接，`ERROR` 与 `FATAL` 也有不同的恢复契约。COPY 客户端 EOF 的 `ERROR` 分支检测到客户端 socket 已经消失；它不建立可复用 socket，也不提供在该连接上发送 `ROLLBACK` 的路径。后者属于 COPY-to-stdout 路径，会关闭后端。本批没有自然 08006 运行，因此这些差异来自固定源码路径和文档规定的事务边界，而不是合成的 socket 实验。

## 代表案例 {#case}

本页没有选定的自然 SQL 运行。结构化证据记录的是源码或定义边界；客户端 `RAISE` 不能代表服务器机制。

## 版本 {#versions}

上面的生成事实表记录锁定的目录快照和最早观察到的定义。本页没有选定的自然 SQL 运行；固定的 REL_18_6/REL_10_23 源码边界不能当作实测结果，也不能据此推断所有中间版本的行为。

## 相关 {#related}

- [`08001` — sqlclient_unable_to_establish_sqlconnection](../08001/)
- [`08007` — transaction_resolution_unknown](../08007/)
- [`40003` — 相关条件](../40003/)

## 来源 {#sources}

- `src.fdw-connection-failure.18.6` — `contrib/postgres_fdw/connection.c` at `REL_18_6` commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`; fixed blob SHA-256 `67fc002657f2c7df6d93cbf99c933cbc103907d1857ed77aedbb85099ea4dda0` ([source](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/postgres_fdw/connection.c#L1462-L1464)).
- `src.copy-connection-failure.10.23` — `src/backend/commands/copy.c` at `REL_10_23` commit `02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4`; fixed blob SHA-256 `0edb032be1ce8d8c90efc28e504aa9e298a2cd26cd374c85da6da0e33ed0915c` ([source](https://github.com/postgres/postgres/blob/02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4/src/backend/commands/copy.c#L525-L527)).
- `src.copy-client-eof.18.6` — `src/backend/commands/copyfromparse.c` at `REL_18_6` commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`; fixed blob SHA-256 `bc42754023579cd782a3cb3f144ad2c2c3d3aa46119eb7567fcdb05f2d445571` ([source](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/commands/copyfromparse.c#L276-L303)).
- `src.copy-client-eof.10.23` — `src/backend/commands/copy.c` at `REL_10_23` commit `02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4`; fixed blob SHA-256 `0edb032be1ce8d8c90efc28e504aa9e298a2cd26cd374c85da6da0e33ed0915c` ([source](https://github.com/postgres/postgres/blob/02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4/src/backend/commands/copy.c#L587-L614)).
- `src.calls.REL_18_6` / `src.calls.REL_10_23` — fixed local call scans, SHA-256 `9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf` / `00d16d3eb01b71ccf1b245c8f3102f9d0ec9f36fb02777b8dd1b99fcb263040c`; these scans preserve the resolved call context used by the claims.