citusdata / citusdata/citus

PG19: propagate the EXPLAIN IO option to worker nodes

Open
#8,770 2 comments 0 reactions 0 assignees View on GitHub
pg19_features
Dominant language
C
Stars
12.8k
Forks
794
Avg merge
2d 14h
Merged PRs (30d)
31

Description

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.

Contributor guide

Open the contributing guide

Research direction

First reproduce EXPLAIN (ANALYZE, IO) on a distributed table using a live PG19 cluster and confirm whether worker IO information is silently dropped. Then read BuildRemoteExplainQuery() in src/backend/distributed/planner/multi_explain.c, compare its PG17 guards, and inspect the pg19-support expected outputs. Done means the IO option reaches worker EXPLAIN statements and the relevant expected outputs pass.

Written by the indexing model from the issue text.

Assessment

Tech stack
c, postgresql
Domain
backend, databases, distributed-systems
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.