From 2d3389c28c5c8235221d2ae0776df4ab812b15c8 Mon Sep 17 00:00:00 2001
From: David Rowley <drowley@postgresql.org>
Date: Sat, 20 Apr 2024 13:53:35 +1200
Subject: [PATCH] Doc: document cases where queryid is stable

The documents were clear that queryid should not be assumed to be stable
between major versions but said nothing about minor versions and left
the reader to guess if that was implied by the mention of the
instability of queryid between major versions.

Here we give minor versions an explicit mention to indicate queryid can
generally be assumed stable between minor versions.

Reviewed-by: Michael Paquier
Discussion: https://postgr.es/m/CAApHDvpYGE6h0cD9UO-eHySPynPj1L3J%3DHxT%2BA7Ud8_Yo6AuzA%40mail.gmail.com
Backpatch-through: 12
---
 doc/src/sgml/pgstatstatements.sgml | 24 +++++++++++++++---------
 1 file changed, 15 insertions(+), 9 deletions(-)

diff --git a/doc/src/sgml/pgstatstatements.sgml b/doc/src/sgml/pgstatstatements.sgml
index 44dd4db7ce..9b0aff73b1 100644
--- a/doc/src/sgml/pgstatstatements.sgml
+++ b/doc/src/sgml/pgstatstatements.sgml
@@ -639,15 +639,21 @@
   </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.
+   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.
+  </para>
+
+  <para>
+   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>