3D000 invalid_catalog_name

目录名称无效

ERROR 已实测详解实测通过

类别: Class 3D 无效的目录名称
严重等级: ERROR
条件名: invalid_catalog_name
宏名称: ERRCODE_INVALID_CATALOG_NAME ERRCODE_UNDEFINED_DATABASE ERRCODE_UNDEFINED_DATABASE
最早已知存在: 7.4
状态: 有效

版本覆盖

19 beta
20 dev

版本条依据已采样构建显示；灰色版本可能尚未采样，悬停可查看。手册链接随版本选择，源码和运行证据保持原核验构建。

速览

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

含义

此码覆盖不止一个阶段的数据库/目录解析。请求数据库不存在时，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。

可复现案例

在一次性实例上执行过的场景。其中 1 个附有可执行 SQL，正文相应小节里给出。

invalid_database PG 10 / 18 有 SQL

前置条件

A runner-owned disposable target is provisioned.

触发

Attempt startup against a generated database name that does not exist.

断言

The selected server diagnostic has the expected SQLSTATE
The selected recovery/probe assertions pass
Runner-owned resources are cleaned up

处置

Follow the case-specific repair statements and verify the resulting state.

清理

Drop the case schema with an owner connection.

实测诊断

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

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

报文模板

源码里的格式串，不是某一次运行的输出。%s 之类是占位符，实际报文会填入对象名与取值。适用范围一栏是核验时留下的原始英文记录，未经翻译。

主消息 database "%s" does not exist

来源：来源：src/backend/utils/init/postinit.c @ REL_18_6 · 来源：src/backend/utils/init/postinit.c @ REL_10_23

代表案例

注册表包含服务器启动 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，不能据此推断所有中间版本的行为。

来源

上游源码 doc/src/sgml/xact.sgml PG18-docs 724edf9bd b48fbe8b
上游源码 src/backend/commands/dbcommands.c 第 806–808 行 REL_10_23 02991e79f cf9e0694
上游源码 src/backend/commands/dbcommands.c 第 1702–1704 行 REL_18_6 724edf9bd 64b77d21
上游源码 src/backend/utils/errcodes.txt REL_18_6 724edf9bd 6e8de346
上游源码 src/backend/utils/init/postinit.c 第 846–848 行 REL_10_23 02991e79f be912628
上游源码 src/backend/utils/init/postinit.c 第 1014–1017 行 REL_18_6 724edf9bd abcf8063
核验材料 verify/cases/3D000/cases.json workspace 4ba3384e
核验材料 verify/cases/3D000/snippets.json workspace 30f24743
核验材料 raw/calls/REL_10_23.jsonl REL_10_23 00d16d3e
核验材料 raw/calls/REL_18_6.jsonl REL_18_6 9ee8a0e8

证据

断言

每条断言都写明了是怎么核实的，以及它不覆盖什么。这一层是核验时留下的原始英文记录，照原样呈现，未经翻译。

3D000 is the invalid_catalog_name condition in Class 3D.

核实方式Read the fixed errcodes.txt definition and the locked catalogue metadata.

不覆盖Directory identity does not identify every backend or client path.

来源来源：src/backend/utils/errcodes.txt @ REL_18_6
The fixed source paths associated with 3D000 report the condition in the mechanism selected for this page.

核实方式Trace the resolved source call records at the fixed release commits and compare their dynamic message fields.

不覆盖Other calls can retain the same SQLSTATE with different context or text.

来源来源：src/backend/utils/init/postinit.c @ REL_18_6 · 来源：src/backend/utils/init/postinit.c @ REL_10_23 · 来源：src/backend/commands/dbcommands.c @ REL_18_6 · 来源：src/backend/commands/dbcommands.c @ REL_10_23
The selected invalid_database case passed with the expected structured diagnostics, recovery assertions, and cleanup on PostgreSQL 18.6 and 10.21.

核实方式Run the shared registry case on isolated runner-owned latest and PG10 targets; inspect the final summaries and raw results.

不覆盖This covers the selected case and versions only; it does not generalize to every driver, proxy, or intermediate release.

来源来源：verify/cases/3D000/snippets.json @ workspace · 来源：verify/cases/3D000/cases.json @ workspace · 运行记录：runtime.3D000-conn-contract-latest.latest · 运行记录：runtime.3D000-conn-contract-pg10.pg10
The selected postinit.c startup path emits 3D000 as FATAL before a session transaction exists, while fixed dbcommands.c paths use the same code in an already-connected SQL command where normal ERROR rollback or savepoint recovery applies.

核实方式Compare the fixed startup and SQL-command source paths with the official transaction recovery contract and the selected startup runtime.

不覆盖The selected runtime covers the startup missing-database path; the SQL-command phase is source-confirmed and has no selected natural runtime in this batch.

来源来源：src/backend/utils/init/postinit.c @ REL_18_6 · 来源：src/backend/commands/dbcommands.c @ REL_18_6 · 来源：doc/src/sgml/xact.sgml @ PG18-docs
The locked catalogue records 3D000 in the listed snapshots; the runtime comparison here is limited to PostgreSQL 18.6 and 10.21.

核实方式Read the generated facts block and locked manifest, then compare the selected target summaries.

不覆盖Presence in a definition file is not an exact behavioral introduction; the two runtime targets do not prove all middle versions.

来源来源：src/backend/utils/errcodes.txt @ REL_18_6 · 来源：raw/calls/REL_18_6.jsonl @ REL_18_6 · 来源：raw/calls/REL_10_23.jsonl @ REL_10_23

运行记录

目标	服务器版本	结果	覆盖案例
latest Disposable runner-owned target only; this is a bounded mechanism case, not a guarantee for every client or network path.	18.6 (Homebrew)	passed	案例：invalid_database
pg10 Disposable runner-owned target only; this is a bounded mechanism case, not a guarantee for every client or network path.	10.21 (Debian 10.21-1.pgdg90+1)	passed	案例：invalid_database

同类 SQL 状态码

状态码	条件名	宏名称	严重等级	版本
Class 3D 无效的目录名称 Invalid Catalog Name 1 个 ↗
3D000	invalid_catalog_name	`ERRCODE_INVALID_CATALOG_NAME`	ERROR	7.4 起已知
数据库名称无法解析，常见于连接不存在的库。				有效

快速链接