doc: Mention de-normalization of deallocated entries in pg_stat_statements

The current implementation of query normalization in pg_stat_statements
is optimistic.  If an entry is deallocated between the post-analyze hook
and the planner and/or execution hook, it can be possible to find query
strings with literal constant values (like "SELECT 1, 2") rather than
their normalized flavor (like "SELECT $1, $2").

This commit adds in the documentation a paragraph about this limitation,
and that this risk can be reduced by increasing pg_stat_statements.max,
particularly if pg_stat_statements_info reports a high number of
deallocations.

Author: Sami Imseih
Discussion: https://postgr.es/m/9CFF3512-355B-4676-8CCC-6CF622F4DC1A@amazon.com

diff --git a/doc/src/sgml/pgstatstatements.sgml b/doc/src/sgml/pgstatstatements.sgml
index 0b40e1eea3affe7ee251ecac6d12ec6d49dd963f..b1214ee6453c9f4f1bc2a6aadcb7149478ca73fa 100644 (file)
--- a/doc/src/sgml/pgstatstatements.sgml
+++ b/doc/src/sgml/pgstatstatements.sgml
@@ -516,6 +516,16 @@
    pg_stat_statements entry.
   
 
+  
+   Queries on which normalization can be applied may be observed with constant
+   values in pg_stat_statements, especially when there
+   is a high rate of entry deallocations. To reduce the likelihood of this
+   happening, consider increasing pg_stat_statements.max.
+   The pg_stat_statements_info view, discussed below
+   in ,
+   provides statistics about entry deallocations.
+  
+
   
    In some cases, queries with visibly different texts might get merged into a
    single pg_stat_statements entry.  Normally this will happen