3D000 — 目录名称无效（invalid_catalog_name）

PostgreSQL SQLSTATE 3D000（目录名称无效，invalid_catalog_name）的源码证据、诊断与处理参考。

3D000 — 目录名称无效

速览

SQLSTATE 3D000 是 Class 3D 中的 invalid_catalog_name。3D000 表示数据库/目录名称无效。请求的数据库不存在时，它可以在启动完成前出现；固定的 dbcommands.c 路径也会在 SQL 命令解析不存在的数据库或模板时发出它。选定启动案例报告 C=3D000、S=FATAL、database "<generated>" does not exist；这只是其中一个阶段，不代表整个类别。

字段	值
SQLSTATE	`3D000`
条件名	`invalid_catalog_name`
状态	`有效`
已知存在于	`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_INVALID_CATALOG_NAME, ERRCODE_UNDEFINED_DATABASE`
别名	`ERRCODE_UNDEFINED_DATABASE`

含义

此码覆盖不止一个阶段的数据库/目录解析。请求数据库不存在时，postinit.c 在启动阶段发出选定的 FATAL；dbcommands.c 则在 SQL 命令解析不存在的数据库或模板时使用同一条件。因此启动记录只是一个具体 producer，不是所有 3D000 的统一描述。

要把阶段作为诊断的一部分。缺失数据库的启动 DSN 产生服务器 FATAL，没有会话级事务；已建立的管理会话执行数据库/模板查找命令时可能产生 ERROR，此时适用普通回滚或保存点恢复。代码本身不能告诉你失败发生在哪个阶段。

阶段指引

阶段	固定 producer	恢复边界
启动选择数据库	`postinit.c` 以 `FATAL` 报告 `database "%s" does not exist`。	从控制数据库修正 DSN 或创建/重命名数据库，再建立新连接；没有可回滚的会话。
SQL 命令或模板查找	`dbcommands.c` 在处理管理命令时使用 `3D000`。	检查命令和事务；显式事务中的 `ERROR` 需要先 `ROLLBACK` 或回到有意建立的保存点。

诊断

检查数据库名、数据库是否被重命名或删除、发生错误的命令阶段，以及可用的控制数据库。选定的 collector 是原始服务器 ErrorResponse 记录，不是 csvlog/jsonlog；原始启动尝试与 psycopg 尝试彼此独立。选定运行使用相互独立的启动尝试：psycopg 的驱动 SQLSTATE 为 null 且没有事务，服务器原始 ErrorResponse 与新鲜的已知数据库探针共同确认服务器码和恢复路径。不要把数据库不存在与 3F000 的 schema 解析混淆。

对于启动失败，检查客户端默认值、URL 解码和环境变量展开后的准确数据库参数，再查看原始服务器 C、S、M 字段。对于已建立会话中的 SQL 命令，另行记录命令文本和事务状态。成功的控制数据库探针只证明可以建立新会话，不证明缺失数据库的原始尝试拥有事务。

处理

使用现有控制数据库检查或创建目标数据库，或修正 DSN/命令目标后重新建立连接。会话启动前没有 ROLLBACK 可执行；SQL 命令路径应在所属管理事务中修复，并重新核对目标目录。

如果数据库是有意删除的，应修正应用目标或迁移，而不是重复同一启动请求。如果管理命令是在已有会话中失败，先恢复该事务，再执行目录修改。重复其他连接发送的工作前先对账；启动失败本身没有在缺失数据库中执行 SQL。

实测诊断

选定的启动分支以 FATAL 发出主报文 database "%s" does not exist，数据库名是动态值。固定的 SQL 命令路径使用同一 SQLSTATE，但外围操作和事务边界可能不同。只有客户端启动异常而没有服务器 ErrorResponse，证据不足。

选定名称 c3d000_missing_cff0e8d38be4 是本次运行生成的值。服务器 ErrorResponse 为 C=3D000、S=FATAL；psycopg 启动的 sqlstate=null 与已知数据库探针属于独立尝试，不是同一会话的其他视图。

代表案例

注册表包含服务器启动 ErrorResponse 后执行的探针。触发点是在新启动连接上使用随机数据库名，失败发生在会话建立前，不能用 SQL 语句重现。

SELECT 1;

18.6 服务器 ErrorResponse 为 C=3D000、S=FATAL、database "c3d000_missing_cff0e8d38be4" does not exist。驱动启动诊断的 SQLSTATE 为 null，失败连接没有事务；已知可用连接探针返回 1，状态 IDLE。

可下载的案例与证据投影分别是 3D000 案例 JSON 和 作者证据。运行器清单为 verify/cases/3D000/cases.json；发布前会将页面 SQL 与共享注册表比对。

版本

上面的生成事实表记录锁定的目录快照和最早观察到的定义。本页自然运行范围是 PostgreSQL 18.6 与 10.21，不能据此推断所有中间版本的行为。

来源

src.postinit-missing-db.18.6 — src/backend/utils/init/postinit.c at REL_18_6 commit 724edf9bde9d356724ad384a2e196edc3c9f80f7; fixed blob SHA-256 abcf80637b153d3aa6f0d2b600943af0a2b4d9a393d05a844db91f8b6b66d0d7 (source).
src.postinit-missing-db.10.23 — src/backend/utils/init/postinit.c at REL_10_23 commit 02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4; fixed blob SHA-256 be912628b29f34afc7b7fbc9d2f480c5ac9cb6ce013a1d992fc7415a311a95ed (source).
src.dbcommands-missing-database.18.6 — src/backend/commands/dbcommands.c at REL_18_6 commit 724edf9bde9d356724ad384a2e196edc3c9f80f7; fixed blob SHA-256 64b77d2197dce16eb1ad19d8168382459d621a03df0b00be157f7db39ca22acf (source).
src.dbcommands-missing-database.10.23 — src/backend/commands/dbcommands.c at REL_10_23 commit 02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4; fixed blob SHA-256 cf9e069415deb7d50ef931048616ae7f9a459d6db64e3d54a0062e8334970ce6 (source).
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.