On Mon, 15 Apr 2024 at 14:09, Michael Paquier <mich...@paquier.xyz> wrote:
>
> On Mon, Apr 15, 2024 at 01:31:47PM +1200, David Rowley wrote:
> > I'm unsure if "Rule of thumb" is the correct way to convey that. We
> > can't really write "We endeavour to", as who is "We". Maybe something
> > like "Generally, it can be assumed that queryid is stable between all
> > minor versions of a major version of ..., providing that <other
> > reasons>".
>
> It sounds to me that the term "best-effort" is adapted here? Like in
> "The compatibility of query IDs is preserved across minor versions on
> a best-effort basis. It is possible that the post-parse-analysis tree
> changes across minor releases, impacting the value of queryid for the
> same query run across two different minor versions.".
I had another try and ended up pushing the logical / physical replica
details up to the paragraph above. It seems more relevant to mention
this in the section which details reasons why the queryid can be
unstable due to metadata variations. I think keeping the 2nd
paragraph for reasons it's stable is a good separation of
responsibility. I didn't include the "best-effort" word, but here's
what I did come up with.
David
diff --git a/doc/src/sgml/pgstatstatements.sgml
b/doc/src/sgml/pgstatstatements.sgml
index 44dd4db7ce..302421306e 100644
--- a/doc/src/sgml/pgstatstatements.sgml
+++ b/doc/src/sgml/pgstatstatements.sgml
@@ -632,22 +632,25 @@
<filename>pg_stat_statements</filename> will consider two
apparently-identical
queries to be distinct, if they reference a table that was dropped
and recreated between the executions of the two queries.
+ 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 identical in all relevant details, so
+ <structfield>queryid</structfield> will not be a useful identifier for
+ accumulating costs across a set of logical replicas.
The hashing process is also sensitive to differences in
machine architecture and other facets of the platform.
Furthermore, it is not safe to assume that
<structfield>queryid</structfield>
will be stable across major versions of
<productname>PostgreSQL</productname>.
+ If in doubt, direct testing is recommended.
</para>
<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
- 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
- identical in all relevant details, so <structfield>queryid</structfield>
will
- not be a useful identifier for accumulating costs across a set of logical
- replicas. If in doubt, direct testing is recommended.
+ Generally, it can be assumed that <structfield>queryid</structfield> values
+ are stable between minor version releases of
<productname>PostgreSQL</productname>,
+ providing that instances are running on the same machine architecture and
+ the catalog metadata details match. Compatibility will only be broken
+ between minor versions as a last resort.
</para>
<para>
