PG19: propagate the EXPLAIN IO option to worker nodes

[ihalatci]

Part of #8597 (Phase 3 — later feature integration).

Problem

PG19 adds a new IO option to EXPLAIN. Citus does not forward it to worker nodes, so for a distributed query the option is silently dropped: the user gets a plan with no worker IO information and no error or warning.

Evidence

Upstream (19beta2):

• src/include/commands/explain_state.h:58 — bool io; /* print info about IO (prefetch, ...) */, new in PG19.
• src/backend/commands/explain_state.c:165 — parses the "io" option into es->io.

Citus:

• src/backend/distributed/planner/multi_explain.c:1226-1259 — BuildRemoteExplainQuery() builds the worker EXPLAIN string from a hand-maintained option list.
• Grepping that file for es->io returns nothing, so the option is never emitted for workers.

Because the option list is an allowlist rather than a passthrough, every new upstream EXPLAIN option defaults to being dropped rather than rejected.

Proposed fix

Add a #if PG_VERSION_NUM >= PG_VERSION_19 branch to BuildRemoteExplainQuery(), mirroring the existing PG17 MEMORY / SERIALIZE guards already in that function at lines 1231-1233, 1240-1242 and 1251-1254. Same shape, no new mechanism.

Related check in the same area

explain_state.c:84,100-101,185 — es->buffers = (buffers_set) ? es->buffers : es->analyze;. In PG19 BUFFERS now defaults on whenever ANALYZE is used. Worth confirming that the pg19-support expected outputs already absorbed this; several stabilization PRs touched EXPLAIN output (#8660, #8680, #8734), so it may already be covered.

Not yet proven

The analysis above is from source shape. It has not been confirmed at runtime that EXPLAIN (ANALYZE, IO) on a distributed table degrades silently rather than erroring. Reproducing that on a live PG19 cluster should be the first step.

Scope

src/backend/distributed/planner/multi_explain.c, plus expected-output updates. Small.

[ihalatci]

Follow-up: body is incomplete, not wrong. The fix needs TWO sites, and the one named above is the secondary one.

Implemented and tested locally. Recording what the body got wrong.

The site the body missed is the decisive one

The body proposed fixing BuildRemoteExplainQuery() only. That function is real and does need the change, but on its own it does not fix the reported symptom, because most distributed EXPLAIN ANALYZE shapes never reach it.

The missing site is ExplainWorkerPlan(), which needs:

if (es->io)
    instrument_option |= INSTRUMENT_IO;

mirroring core at explain.c:525. On that path Citus recomputes instrument_option itself, so forwarding the option text is not enough - without INSTRUMENT_IO the worker collects no I/O counters and Prefetch: never appears.

Two sites, two genuinely different mechanisms

Path	Who instruments	What is required
saved-plan (worker_save_query_explain_analyze)	Citus, via its own instrument_option	INSTRUMENT_IO in ExplainWorkerPlan()
BuildRemoteExplainQuery()	core PG, worker runs a real EXPLAIN (ANALYZE, ..., IO)	option text on the wire

Which path a task takes is decided at multi_explain.c:926:

if (es->analyze && task->fetchedExplainAnalyzePlan)   /* saved plan */
else                                                  /* BuildRemoteExplainQuery */

so it is not es->analyze alone. fetchedExplainAnalyzePlan is populated only for tasks rewritten by ExplainAnalyzeTaskList(), whose sole caller is gated on RequestedForExplainAnalyze(scanState) (es_instrument != 0 || (SubPlanLevel > 0 && SubPlanExplainAnalyzeContext)). So the invariant is: a task has a saved plan iff its task list was executed under a scan node where that disjunction held - a property of the execution context, not of the task type.

The "not yet proven" item in the body is now proven, in both directions

Runtime confirmation was done by instrumenting BuildRemoteExplainQuery() and running the full multi_schedule: 1112 calls with analyze=0, 2 with analyze=1. So the second path is genuinely reachable under ANALYZE, which an earlier round of analysis had wrongly concluded was impossible. The in-tree comment at multi_explain.c:922-925 is therefore accurate but not exhaustive: it attributes the NULL saved plan to EXPLAIN EXECUTE, while the reproduced shape is a CTE-wrapped INSERT ... RETURNING. There is more than one route.

Safety

Core rejects IO without ANALYZE at the coordinator (explain_state.c:193-197, errmsg("EXPLAIN option %s requires ANALYZE", "IO")), so IO TRUE, ANALYZE FALSE can never reach a worker, and IO FALSE on non-analyze paths does not trip core's es->io && !es->analyze check. All four analyze x io combinations are safe.

Every PG19 use is behind #if PG_VERSION_NUM >= PG_VERSION_19, so PG17/18 builds never emit the token.

Scope estimate in the body was right

3 files, +171/-0, mostly tests. Validated with a 3-phase negative control (fix present -> pass, fix reverted with test kept -> fail, fix restored -> pass), md5-verified at each phase.

[ihalatci]

Status: a local implementation has been built and runtime-validated, but no published commit/PR exists. Local solution: two required sites—set INSTRUMENT_IO in ExplainWorkerPlan() and propagate the IO option through BuildRemoteExplainQuery(); 3 files, mostly tests, negative control validated. Needs: clean committed SHA, release review, explicit publication approval, and PR.