Re: pgstat: Flush some statistics within running transactions, take 2

On Wed, Sep 09, 2026 at 12:50:55PM +0900, Michael Paquier wrote:
> All that said, I finish with the attached for 0001 (+commit message
> edits). How does this part look?

While I don't forget, this piece of 0002 is worth its own change:

+ <row>
+ <entry role="func_table_entry"><para role="func_signature">
+ <indexterm>
+ <primary>pg_stat_force_next_flush</primary>
+ </indexterm>
+ <function>pg_stat_force_next_flush</function> ()
+ <returnvalue>void</returnvalue>
+ </para>
+ <para>
+ Flushes the statistics pending in the current session to shared
+ memory, making them visible to other sessions. When called within
+ a transaction, counters tracking data modifications, such as the
+ numbers of inserted, updated, and deleted tuples, are deferred
+ until the transaction ends.
+ </para></entry>
+ </row>

FWIW, I have used it in some out-of-core tests to accelerate some
logic based on many stats lookups, and only knew about it because of
my knowledge of the core code (test script went down from 8s to 1s-ish
mostly thanks to this function on my laptop, due to waits for the
stats lookups previously).

I think that we should add it to the docs, with a slightly different
description, and without mentioning any transactional behavior as a
starting point. Say:
"Forces the statistics accumulated by the current session to be
flushed to shared memory at the end of current transaction, without
waiting for the usual <varname>PGSTAT_MIN_INTERVAL</varname> delay
between flushes. This is mainly useful when writing tests so as the
statistics are generated by a session in a predictable way."

Then we should update this text once a flavor of 0002 gets merged.
--
Michael