I was recently asked internally about the stability guarantees we
offer for queryid. My answer consisted of:
1. We cannot change Node enums in minor versions
2. We're *unlikely* to add fields to Node types in minor versions, and
if we did we'd likely be leaving them out of the jumble calc, plus it
seems highly unlikely any new field we wedged into the padding would
relate at all to the parsed query.
While answering, I checked what our documentation says. It does not
seem to offer much in the way of what is guaranteed between minor
versions.
In [1] I see:
"As a rule of thumb, queryid values can be assumed to be stable and
comparable only so long as the underlying server version"
It's the "underlying server version" that I think needs some
clarification. It's unclear if the minor version must match or just
the major version number. The preceding paragraph does mention:
"Furthermore, it is not safe to assume that queryid will be stable
across major versions of PostgreSQL."
but not stable across *major* versions does *not* mean stable across
*minor* versions. The reader is just left guessing if that's true.
Maybe the paragraph starting with "Consumers of" can detail the
reasons queryid might be unstable and the following paragraph can
describe the scenario for when the queryid can generally assumed to be
stable.
I've drafted a patch which I think improves things, but it probably
needs more work and opinions.
David
[1] https://www.postgresql.org/docs/current/pgstatstatements.html
diff --git a/doc/src/sgml/pgstatstatements.sgml
b/doc/src/sgml/pgstatstatements.sgml
index 44dd4db7ce..4c8288fa3b 100644
--- a/doc/src/sgml/pgstatstatements.sgml
+++ b/doc/src/sgml/pgstatstatements.sgml
@@ -640,8 +640,9 @@
<para>
As a rule of thumb, <structfield>queryid</structfield> values can be
assumed to be
- stable and comparable only so long as the underlying server version and
- catalog metadata details stay exactly the same. Two servers
+ stable and comparable only between <productname>PostgreSQL</productname>
instances
+ which are running the same major version of
<productname>PostgreSQL</productname>
+ and are running on the same machine architecture and catalog metadata
details match. Two servers
participating in replication based on physical WAL replay can be expected
to have identical <structfield>queryid</structfield> values for the same
query.
However, logical replication schemes do not promise to keep replicas
