Document new statement reset behavior by seanlinsley · Pull Request #388 · pganalyze/pganalyze-docs

seanlinsley · 2026-03-19T15:51:29Z

This documents the new pg_stat_statements reset behavior in pganalyze/collector#775

I decided to remove the "Collector times out" page because statement text collection timeouts should be largely resolved ever since we delayed pg_query calls until after the SELECT query was complete.

lfittl

Overall looks good - I'll take one more look after wording adjustments are done.

lfittl · 2026-03-25T22:06:49Z

@@ -1,54 +0,0 @@
---


We should make sure to add a redirect via the nginx config in the web repo.

lfittl · 2026-03-25T22:08:01Z

+---
+
+If the collector is using too much memory or `<query text unavailable>` is showing up in pganalyze,
+you may want to set up an automatic reset of pg_stat_statements.


Suggested change

you may want to set up an automatic reset of pg_stat_statements.

you may want to set up an automatic reset of `pg_stat_statements`.

lfittl · 2026-03-25T22:08:56Z

+
+## &lt;query text unavailable&gt;
+
+Some versions of Postgres aren't able to accurately normalize queries (e.g. those with variable bind params),


Suggested change

Some versions of Postgres aren't able to accurately normalize queries (e.g. those with variable bind params),

Earlier versions of Postgres aren't able to group certain queries together (e.g. those using `IN` lists of variable lengths),

lfittl · 2026-03-25T22:11:32Z

+
+Some versions of Postgres aren't able to accurately normalize queries (e.g. those with variable bind params),
+leading to many duplicate entries that often have very low call counts. When `pg_stat_statements.max` is reached,
+Postgres will deallocate (remove) the entries with the lowest call count. In periods of high database activity


Suggested change

Postgres will deallocate (remove) the entries with the lowest call count. In periods of high database activity

Postgres will deallocate (remove) entries based on their usage, which is based on the call count. In periods of high database activity

lfittl · 2026-03-25T22:11:55Z

+this can happen so so quickly that the collector isn't able to capture the query text, causing
+`<query text unavailable>` to show up in pganalyze.
+
+This can be addressed by enabling the Maximum Query Stats Reset Frequency setting. We recommend a setting of


Suggested change

This can be addressed by enabling the Maximum Query Stats Reset Frequency setting. We recommend a setting of

This can be addressed by enabling the "Maximum Query Stats Reset Frequency" setting in pganalyze. We recommend a setting of

lfittl · 2026-03-25T22:15:03Z

+
+## Setup
+
+Collector version 0.70.0 or later is required.


We could link this to the collector release changelog.

lfittl · 2026-03-25T22:15:33Z

+After enabling the Maximum Query Stats Reset Frequency setting on the server settings page (and optionally tuning
+    Maximum Query Size Before Next Reset), the collector will automatically start performing resets when needed.


Suggested change

After enabling the Maximum Query Stats Reset Frequency setting on the server settings page (and optionally tuning

Maximum Query Size Before Next Reset), the collector will automatically start performing resets when needed.

After enabling the "Maximum Query Stats Reset Frequency" setting on the server settings page (and optionally tuning

"Maximum Query Size Before Next Reset"), the collector will automatically start performing resets when needed.

lfittl · 2026-03-25T22:17:31Z

+
+Collector version 0.70.0 or later is required.
+
+After enabling the Maximum Query Stats Reset Frequency setting on the server settings page (and optionally tuning


I think it'd be good to keep a server settings page screenshot here, possibly with the relevant two settings highlighted with a red border or similar to make it very clear what needs to be changed.

lfittl · 2026-03-25T22:20:42Z

+$$
+  /* pganalyze-collector */ SELECT * FROM public.pg_stat_statements_reset();
+$$ LANGUAGE sql VOLATILE SECURITY DEFINER;`}
+</CodeBlock>


I wonder if we should put a section after this that talks about reducing pg_stat_statements churn, and specifically references how different Postgres versions have addressed different problems that can occur (and explain when upgrading helps, and to which version). That would also be a good place to talk about pg_stat_statements.max, which I think is still relevant as a fix for this kind of problem.

lfittl · 2026-03-25T22:22:48Z

@@ -0,0 +1,46 @@
+---
+title: Reducing memory usage and query text unavailable


Suggested change

title: Reducing memory usage and query text unavailable

title: Query text unavailable and reducing memory usage

msakrejda

Looks great.

msakrejda · 2026-04-09T20:17:34Z

+- Utility statements including a random comment (like a request ID), which can be addressed by
+  upgrading to Postgres 16 or by setting `pg_stat_statements.track_utility = off`
+- Dynamically-generated queries with varying column lists or where clauses, which can be addressed by
+  increasing `pg_stat_statements.max`


Should we say something like

Suggested change

increasing `pg_stat_statements.max`

increasing `pg_stat_statements.max` (the trade-off is higher memory usage in Postgres)

? I think whenever there's a setting we recommend changing, we should note the trade-offs unless they're obvious. I guess they're kind of obvious here?

* mcp: add api authentication docs, and note about rate limiting * update hierarchy * rewrites * Keiko review feedback Co-authored-by: Keiko Oda <keiko713@gmail.com> * Document new statement reset behavior (#388) --------- Co-authored-by: Keiko Oda <keiko713@gmail.com>

Document new statement reset behavior

cbbe9e3

seanlinsley requested review from lfittl and msakrejda March 19, 2026 15:51

Fix link formatting, rename page title

c000fa6

lfittl reviewed Mar 25, 2026

View reviewed changes

seanlinsley added 3 commits March 26, 2026 09:39

Apply rewording changes, reflow text

a198066

Add server settings image

922c37a

Explain sources of churn

1b59336

seanlinsley requested a review from lfittl March 26, 2026 14:13

msakrejda approved these changes Apr 9, 2026

View reviewed changes

Note that increasing pg_stat_statements.max uses more memory

abddf78

seanlinsley merged commit c92b4d7 into main Apr 9, 2026

seanlinsley deleted the reset_stat_statements branch April 9, 2026 20:22

jensy pushed a commit that referenced this pull request Apr 10, 2026

Document new statement reset behavior (#388)

88d59e8

Navigation Menu

Uh oh!

Document new statement reset behavior - #388

Document new statement reset behavior#388
seanlinsley merged 6 commits into
mainfrom
reset_stat_statements

seanlinsley commented Mar 19, 2026 •

edited

Loading

Uh oh!

lfittl left a comment

Uh oh!

lfittl Mar 25, 2026

Uh oh!

lfittl Mar 25, 2026

Uh oh!

lfittl Mar 25, 2026

Uh oh!

lfittl Mar 25, 2026

Uh oh!

lfittl Mar 25, 2026

Uh oh!

lfittl Mar 25, 2026

Uh oh!

lfittl Mar 25, 2026

Uh oh!

lfittl Mar 25, 2026

Uh oh!

lfittl Mar 25, 2026

Uh oh!

lfittl Mar 25, 2026

Uh oh!

msakrejda left a comment

Uh oh!

msakrejda Apr 9, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	you may want to set up an automatic reset of pg_stat_statements.
	you may want to set up an automatic reset of `pg_stat_statements`.


		## <query text unavailable>

		Some versions of Postgres aren't able to accurately normalize queries (e.g. those with variable bind params),

	Some versions of Postgres aren't able to accurately normalize queries (e.g. those with variable bind params),
	Earlier versions of Postgres aren't able to group certain queries together (e.g. those using `IN` lists of variable lengths),

	Postgres will deallocate (remove) the entries with the lowest call count. In periods of high database activity
	Postgres will deallocate (remove) entries based on their usage, which is based on the call count. In periods of high database activity

	This can be addressed by enabling the Maximum Query Stats Reset Frequency setting. We recommend a setting of
	This can be addressed by enabling the "Maximum Query Stats Reset Frequency" setting in pganalyze. We recommend a setting of

		After enabling the Maximum Query Stats Reset Frequency setting on the server settings page (and optionally tuning
		Maximum Query Size Before Next Reset), the collector will automatically start performing resets when needed.


		Collector version 0.70.0 or later is required.

		After enabling the Maximum Query Stats Reset Frequency setting on the server settings page (and optionally tuning

		@@ -0,0 +1,46 @@
		---
		title: Reducing memory usage and query text unavailable

	title: Reducing memory usage and query text unavailable
	title: Query text unavailable and reducing memory usage

	increasing `pg_stat_statements.max`
	increasing `pg_stat_statements.max` (the trade-off is higher memory usage in Postgres)

Uh oh!

Conversation

seanlinsley commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lfittl left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msakrejda left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

seanlinsley commented Mar 19, 2026 •

edited

Loading