PostgreSQL 的 EXPLAIN 不支持直接对含占位符（如 $1）的语句生成执行计划，需通过强制通用计划模式（plan_cache_mode = force_generic_plan）配合预编译语句与 EXPLAIN EXECUTE 实现，本文详解操作步骤、适用场景及关键注意事项。
postgresql 的 explain 不支持直接对含占位符（如 `$1`）的语句生成执行计划，需通过强制通用计划模式（`plan_cache_mode = force_generic_plan`）配合预编译语句与 `explain execute` 实现，本文详解操作步骤、适用场景及关键注意事项。
在 Oracle 中，EXPLAIN PLAN FOR SELECT ... WHERE col = :1 可直接返回完整执行计划，无需提供实际参数值；而 PostgreSQL 默认要求所有参数具备具体类型和值，否则会报错（如 ERROR: there is no parameter $1 或类型不匹配），这是因为 PostgreSQL 的查询规划器在解析阶段即需确定参数类型与统计信息，以选择最优计划——这导致其天然不支持“纯占位符式”的静态计划分析。
所幸，PostgreSQL 提供了绕过此限制的可靠方案：启用通用计划模式 + 预编译语句 + NULL 值执行解释。该方法不依赖真实业务数据，兼顾安全性与计划完整性，适用于 SQL 审计、性能基线建立或 DevOps 自动化分析等场景。
✅ 正确操作流程（以 character varying, integer, timestamp 为例）
-- 1. 临时设置会话级通用计划模式（仅影响当前会话）
SET plan_cache_mode = force_generic_plan;
-- 2. 创建带占位符的预编译语句（类型由首次调用推断，建议显式 cast 确保一致性）
PREPARE sample_query(text, integer, timestamp) AS
SELECT * FROM sample_table
WHERE text_col = $1
AND int_col = $2
AND ts_col = $3;
-- 3. 使用 NULL（或类型兼容的默认值）执行 EXPLAIN —— 注意：NULL 在多数情况下可被正确推导类型
EXPLAIN (FORMAT YAML) EXECUTE sample_query(NULL, NULL, NULL);? 为什么用 NULL？
- 对于 text/character varying 和 integer，NULL 可被准确识别为对应类型；
- 对于 timestamp，NULL 同样有效（PostgreSQL 9.6+ 支持 NULL::timestamp 隐式解析）；
- 若遇类型歧义（如函数重载场景），可显式转换：EXPLAIN EXECUTE sample_query(NULL::text, NULL::int, NULL::timestamptz)。
⚠️ 关键注意事项
- force_generic_plan 是会话级设置：仅对当前连接生效，不影响其他会话，生产环境使用后建议及时重置（RESET plan_cache_mode）；
- 通用计划 ≠ 最优计划：它忽略具体参数值，基于列统计信息生成“平均情况”计划，可能与真实执行路径存在差异（尤其在数据倾斜严重时）；
- 避免在事务中误用：PREPARE 语句在事务提交后仍存在，但 EXPLAIN EXECUTE 必须在 PREPARE 后执行，且不能跨事务；
-
替代方案对比：
- EXPLAIN ANALYZE + 真实参数：准确但暴露敏感数据，不满足数据合规要求；
- pg_stat_statements + queryid：适用于已执行语句的回溯分析，无法预测未运行语句；
- 第三方工具（如 pg_hint_plan）：需额外部署，且不解决占位符解析本质问题。
? 总结
PostgreSQL 虽无 Oracle 式的原生占位符 EXPLAIN，但通过 plan_cache_mode = force_generic_plan + PREPARE/EXECUTE 组合，即可安全、可控地获取参数化查询的通用执行计划。该方案已被广泛验证于 CI/CD SQL 检查、DBA 审计脚本及 APM 工具集成中。值得注意的是，PostgreSQL 16 已合并相关补丁（CF #3962），未来将支持更简洁的 EXPLAIN [PLAN] FOR ... 语法——开发者可关注社区进展并参与测试反馈。
