55P02 — cant_change_runtime_param

PostgreSQL SQLSTATE 55P02 的来源与诊断参考。

55P02

速览

55P02 表示 PostgreSQL 因 GUC 上下文或服务器生命周期阶段不允许，而拒绝修改运行时参数。同一条件名覆盖只能重启、只能 SIGHUP、只能在 backend 启动时、内部参数以及 binary-upgrade guard 等路径。

字段	值
SQLSTATE	`55P02`
条件名	`cant_change_runtime_param`
状态	`有效`
已知存在于	`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_CANT_CHANGE_RUNTIME_PARAM`
别名	`—`

含义

set_config_with_handle() 使用 ereport(elevel, ...)，所以客户端看到的 severity 取决于调用者：SQL SET 通常使用 ERROR，配置文件、数据库/角色设置等路径可能使用 LOG 或 WARNING。源码先检查 GUC context：内部参数不能由普通调用者修改；PGC_POSTMASTER 参数需要重启；PGC_SIGHUP 参数在 session 中修改会报 parameter "%s" cannot be changed now；backend 或 superuser-backend 参数在连接启动后修改会报 parameter "%s" cannot be set after connection start。重启提示也用于重载时试图改变 postmaster 参数的情形，ALTER SYSTEM 还会拒绝不能写入其配置文件的参数。

pg_upgrade_support.c 另有 binary-upgrade guard：IsBinaryUpgrade 为假时，升级辅助函数报此码。这是内部管理前置条件，不是普通 pg_settings.context 判断。

消息

内部参数或配置文件拒绝：primary 为 parameter "%s" cannot be changed；set_config_with_handle() 的调用者提供 severity，而 ALTER SYSTEM guard 使用 ERROR。
只能重启的参数：primary 为 parameter "%s" cannot be changed without restarting the server；severity 由调用者提供。
在 session 中修改 SIGHUP 参数：primary 为 parameter "%s" cannot be changed now；severity 由调用者提供。
连接启动后修改 backend 参数：primary 为 parameter "%s" cannot be set after connection start；severity 由调用者提供。
binary-upgrade 模式外调用升级 helper：primary 为 function can only be called when server is in binary upgrade mode，ERROR。

诊断

记录参数名、完整 primary message、设置来源（SET、启动选项、配置重载、数据库/角色设置、ALTER SYSTEM 或 binary-upgrade helper）及服务器阶段。检查 pg_settings.context、pending_restart、source 和 sourcefile：postmaster 指向重启，sighup 指向 reload，backend 指向新连接。值格式错误属于其他 SQLSTATE，不能只凭 55P02 判断。

用户发出的 SET 若以 ERROR 失败，会使显式事务进入错误状态；配置重载或后台路径可能只记录日志或发 WARNING，并不等于客户端事务被回滚，要以实际 severity 和连接状态为准。

处理

按 pg_settings 指示的上下文修改：只能重启的值写入配置后重启，SIGHUP 值执行 reload，backend 值在新 session 中设置，内部或 binary-upgrade 参数交给所属机制。显式事务中的 SQL SET 失败后，先执行 ROLLBACK 或 ROLLBACK TO SAVEPOINT，再继续发送命令。autocommit 下先修正生命周期或设置来源，再重试；不要盲目重复同一被拒绝的操作。转换完成后核对实际生效值。