pganalyze Blog - Articles by Ryan Booz

Postgres in Production Special Series: Diagnosing High Cardinality Workloads in pg_stat_statements (Part 6)

Ryan Booz — Thu, 13 Aug 2026 12:00:00 GMT

In Part 6 of this special Postgres in Production deep dive series, Ryan Booz asks a question that determines how useful pg_stat_statements can be for you at all: do you have a high cardinality workload? This episode covers what that actually means, why ORMs, dynamic SQL, and AI-assisted development tools generate more unique queries than you might expect, a side by side demo of the same workload on Postgres 17 and Postgres 18, and the concrete checks that tell you whether pg_stat_statements is losing the data you need for query tuning.

Share this episode: Click here to share this episode on LinkedIn. Feel free to sign up for our newsletter and subscribe to our YouTube channel.

A quick recap
What a high cardinality workload means
Where the unique queries come from
A demo: overwhelming pg_stat_statements with Bluebox
Our databases are hidden behind our tools
How to tell if you have a high cardinality workload
Taking action
What happens if you don’t
Key takeaways
What’s coming next
What we discussed

Transcript

A quick recap

Over the first five episodes we covered what pg_stat_statements is and the metrics it stores (Part 1), what makes a statement “unique” through normalization (Part 2), where the query texts live on disk (Part 3), how new metrics get stored and old ones get deallocated (Part 4), and the configuration settings that control all of it (Part 5).

Through all of that, I have probably mentioned the pg_stat_statements.max setting at least 100 times, because it’s so crucial to understanding how effective the data is that you have. This episode is about the workloads that consistently outrun that setting, and being able to identify whether you’re in that situation is really helpful to determining if pg_stat_statements can help you do the query tuning and optimization that you need it to.

What a high cardinality workload means

When I say high cardinality, what does it really mean? To me, it means something like this: if you have a workload that’s consistently generating more unique normalized queries than the pg_stat_statements.max capacity, then you really have a high cardinality workload from a pg_stat_statements perspective. The extension isn’t able to consistently retain the metrics that can help you find the queries that are most in need of being optimized.

Now, I can hear a lot of you say, and quite honestly, I’ve said this myself: “My application isn’t that complex. There’s no way I’m suffering from something like this. The data must be there somewhere, I just can’t find it.” Well, that’s not always the case.

It’s often the tooling we’re using that hides the SQL that’s being generated behind the scenes. We know that the tool is abstracting the SQL for us, but we might not fully understand the effect it’s having on our query metrics.

Where the unique queries come from

It might be the ORM and the way it generates unique SQL statements for different clients, customers, and tenants. Maybe it’s custom dynamic SQL that you yourself have written. I’ve done this often in stored procedures, and if I’m running with pg_stat_statements.track = all, that dynamic SQL produces unique statements over and over again.

Maybe it’s ad hoc reporting. All of us are connecting more and more tools to our database, including AI systems, and those tools generate a plethora of queries as they attempt to navigate the information needed to satisfy the request. Lots of ad hoc querying can fill up pg_stat_statements very quickly.

And we’ve talked often in this series about variable length IN lists in Postgres 17 and below, not to mention dynamic column select lists with otherwise similar queries.

A demo: overwhelming `pg_stat_statements` with Bluebox

I want to show you a brief demo of exactly how easy it is to overwhelm pg_stat_statements, with a tool you could actually test this with yourself. I’ll use the load generation tool included with the Bluebox sample database, a sample database I’ve created and made available open source to the community for testing and demonstrations like this.

About an hour before recording this video, I started this load generation with the exact same settings on a Postgres 17 database and a Postgres 18 database. The load testing project has about 30 different scenarios, each created for very specific kinds of query shapes and data requests. Most of them have one or two SQL parameterized statements included, executed directly on the database without the use of an ORM. In total, there are fewer than 50 actually unique text statements in the entire project.

But a couple of them, like batch_film_lookup, take a list of anywhere from one to 200 film IDs and look them up. On Postgres 17 or below, that becomes really easy to turn into a lot of unique load: all it takes is a WHERE IN clause and lots of unique lists of film IDs.

After about an hour of running, Postgres 17 has 671 unique statements inside of pg_stat_statements. The exact same workload on Postgres 18 has 120 unique statements. That is one of the improvements we’ve talked about a number of times through this series: in Postgres 18 and above, those IN lists are normalized down to one statement.

Another way to visualize this is to look at the queries with those IN lists. One example load query looks up data based on lists of customer IDs. On Postgres 17, we can see dozens of the same query except for the WHERE IN clause that shows a unique list each time: one has many customer IDs, another has four or five, and so on. On Postgres 18, the same query produces only two entries.

You might ask why two, if Postgres 18 collapses all of this. Some of it has to do with the tooling: the first time it sends a parameterized query, it also has to send the value types, and it often sends a generic type like numeric when it isn’t 100% sure what the type is. Once it gets a response back, the tooling can sometimes adjust and from that point forward sends the correct data type, for instance an integer instead of numeric. This is often why you’ll see a few extra entries for a query text even on Postgres 18.

The sample load test is a really easy way to see the impact of a seemingly simple query workload on pg_stat_statements, and you can use the tool to test it yourself. Grab Bluebox, read the instructions on how to start the load testing, and configure it against one of your sample Bluebox databases.

Our databases are hidden behind our tools

More than ever, I think we’re experiencing higher and higher cardinality query workloads because our databases are hidden and abstracted from our day to day developer work. The reason is staring us right in the face in this modern age: ORMs and data access tools let us use our own objects and object notation to get the data we want, letting the framework write the queries, hopefully as effectively as possible. But we’ve all experienced time and again how inefficient they can be as our applications and databases get more complex.

Additionally, we now have dozens of AI-assisted development tools that freely query the database based on a schema, in ways they decide are best. Even in my own development sessions using a number of these tools, I see significant numbers of pg_stat_statements data being created, because the tooling combs for specific bits of information with unique one-off queries. If it can’t find what it needs, it will keep iterating and changing the queries to get to the next step of its task as quickly as possible.

How to tell if you have a high cardinality workload

So how do you diagnose it? First, you have to know what pg_stat_statements.max is set to. I’m sorry to mention it yet again, but it really is the most essential setting in pg_stat_statements for how effectively you can find the data you need, dependent on your workload.

Second, how close are you to actually hitting that limit? If your statement count is always at the 95% threshold, it’s a pretty sure bet that deallocations have been going on. You could try resetting pg_stat_statements and watching whether it fills back up quickly. I’ve worked with clients that have it set to 5,000 or even 10,000, and when they reset the metrics, the hash table refills in less than 30 minutes. That’s a really good indicator of how large your workload is and how quickly you can use that information before it’s gone again.

Third, is the deallocation counter climbing? When you query pg_stat_statements_info, do you see that number going up every so often, even once or twice a day, let alone once or twice an hour?

Fourth, how often do you search for query text that doesn’t exist in pg_stat_statements? I often hear people ask: “I know I have a query that’s running in my code. Why isn’t it in pg_stat_statements?” The short and simple answer is, “It’s probably getting lost”. If you consistently try to find a statement you know the text of, querying by the first few lines, and you can’t find it, it’s being deallocated more quickly than you can get the metrics for it. That is a high cardinality workload.

And one last test: your top queries. What you consider a top query might change depending on what you’re trying to achieve, but often we start with total execution time, how much total time a query has taken in execution since pg_stat_statements started tracking it. If you order by that and the top 10 changes pretty frequently, while you believe your workload is pretty consistent, then you probably have a high cardinality workload.

Taking action

If you do have a high cardinality workload, it really is time to take action. You can’t just hope this is going to fix itself.

First, go back and watch episode five, where we reviewed all of the settings in pg_stat_statements, the ones you can change on the fly and the ones that require a restart. Next, consider upgrading to Postgres 18, which was one of the suggestions I gave at the end of that episode.

Then there are the things to look at in your ORM and AI tooling. Talk about it with your development teams: help them understand that when a query suggestion comes out of these tools, there are patterns to look for that might be problematic.

And honestly, I suggest you keep notes of when pg_stat_statements seemed to lack the information you needed. Is there any consistency to it? Maybe every Monday morning you go to find queries and you can’t, because big data transformation jobs ran over the weekend and flooded pg_stat_statements, pushing out information from the week before that you wanted for identifying problems.

What happens if you don’t

Ultimately, if you don’t take action, tuning just becomes a lot harder in Postgres. You don’t have all the information you need to find problematic queries. Your history becomes shorter, so even if you think you’ve fixed something, it’s hard to identify whether the fix had the intended outcome. And the optimization decisions you make become a little less trustworthy over time, because you’re never sure they really had the intended impact.

Key takeaways

A high cardinality workload means your queries outrun your capacity. If your workload consistently generates more unique normalized queries than pg_stat_statements.max can hold, pg_stat_statements can’t retain the metrics you need for tuning.
The uniqueness usually comes from tooling. ORMs generating per-tenant statements, custom dynamic SQL (especially with track = all), ad hoc reporting, AI-assisted development tools, and IN lists on Postgres 17 and below.
Postgres 18 makes a measurable difference. The same one hour Bluebox workload produced 671 unique statements on Postgres 17 and 120 on Postgres 18, thanks to IN list normalization.
Five checks diagnose it. Know your max; watch how fast the table refills after a reset; watch the deallocation counter in pg_stat_statements_info; check whether queries you know are running go missing; and watch whether your top 10 by total execution time churns.
Settings buy relief, but the cause lives in your application. Revisit the episode 5 settings, consider Postgres 18, and work with your development teams on the query patterns your tools produce.

What’s coming next

In our last episode we’ll talk about a couple of ways to use pg_stat_statements, including some of the queries we recommend, so that you can more effectively find the queries that are most impacting your workload. Please join us next time for episode seven of this deep dive into pg_stat_statements.

I hope this series helps you better understand one of the most essential tools in the Postgres ecosystem. Feel free to subscribe to our YouTube channel, sign up for our newsletter or follow us on LinkedIn to get updates about new episodes!

What we discussed

Earlier parts in the pg_stat_statements deep dive series:

Postgres in Production Special Series: Configuring pg_stat_statements to Reduce Deallocations (Part 5)

Ryan Booz — Tue, 30 Jun 2026 12:00:00 GMT

In Part 5 of this special Postgres in Production deep dive series, Ryan Booz turns to configuration. There are only a handful of settings that control how pg_stat_statements behaves, but they decide how much data you keep and how much you lose. This episode covers how to see when you’re losing data through deallocations, what each setting actually does, and the changes (in settings and in your application) that reduce data loss over time.

Share this episode: Click here to share this episode on LinkedIn. Feel free to sign up for our newsletter and subscribe to our YouTube channel.

A quick recap
Why deallocations matter
Seeing deallocations: the pg_stat_statements_info view
Sampling the deallocation counter (the 10-minute window)
What the deallocation numbers mean
The configuration settings
Reducing deallocations through settings
Reducing deallocations in your application
Key takeaways
What’s coming next
What we discussed in this episode

Transcript

A quick recap

In the first four episodes we covered what pg_stat_statements is and the metrics it stores (Part 1), what makes a statement “unique” through normalization of the query text (Part 2), and where those query texts actually live on disk (Part 3). In Part 4 we walked through the entire process of storing new incoming metrics.

pg_stat_statements is our main view into what’s happening with completed query executions, and we’ve gotten a lot of value from it. But we also discussed an issue many people aren’t aware of when they analyze this data: deallocations. This episode is about the configuration that controls them.

Why deallocations matter

In order to store all the information coming in, pg_stat_statements sometimes has to remove previously stored data to make room for new information. One of the extension’s settings determines how often and when that happens.

If you aren’t tracking this, you have no idea how much data you could be losing over time. The good news is that the loss is measurable.

Seeing deallocations: the pg_stat_statements_info view

The pg_stat_statements_info view exposes a deallocation counter. In one example server, since the server started (or the stats were last reset), pg_stat_statements had deallocated 46 times. With the default pg_stat_statements.max of 5,000, each deallocation drops 5% of the table, or 250 rows. So 250 rows of metrics had been dropped 46 times since that server began.

If you aren’t tracking it yourself, your monitoring tool might be. In pganalyze we show this to you over a 10-minute window, with a counter for each server. In one example, over a 10-minute window a server (again at the default max of 5,000) deallocated twice, which means roughly every five minutes 250 rows of metrics were dropped to make room for new ones.

Sampling the deallocation counter (the 10-minute window)

Taking a sample of the deallocation counter is easy, and something you should do periodically. You query pg_stat_statements_info and read the deallocation counter. A 10-minute window is a good timeframe because it makes the per-second math easy to reason about.

If you query the view, wait 10 minutes, query it again, and the counter hasn’t moved, you’re in a good state. Most reasonable monitoring tools query pg_stat_statements at least once every 10 minutes, so you’re likely retaining as much data as you can.

What the deallocation numbers mean

Here’s how to read the counter over a 10-minute window. If it’s gone up by about 10, that means roughly every minute you’re losing 5% of the rows in the hash table. That’s a little concerning, especially if your monitoring tool isn’t querying often enough to catch the data before it’s dropped. Once you reach about 100 deallocations per 10 minutes, you’re losing 5% of your rows every six seconds or so, which is a lot of contention and really concerning. And believe it or not, I’ve seen numbers at 600 and above. At that point pg_stat_statements is trying to deallocate enough rows roughly every second to make room for new information, which is a lot of locking and effort on your metrics table, and you’re very likely losing information that would help you tune your database.

The configuration settings

The settings below come straight out of the Postgres documentation, and you can read about them there yourself.

pg_stat_statements.max

We’ve talked about this one in every episode, so I’ll keep it short, with two things worth repeating. The first is that a restart is required: if you decide to raise this value because you have a lot of deallocations, you have to plan downtime for it, and there’s no workaround, which is a real concern if you’re already having a problem. The second is that it reserves memory even if tracking is off. As long as the extension is loaded, it reserves enough shared memory for the maximum number of rows, because the schema is fixed and it knows how much it needs. That’s usually not much, a few to tens of megabytes, but it is reserved.

pg_stat_statements.track

This one can be changed with a configuration reload, and it has three options. By default it’s set to top, which tracks only top-level queries. Setting it to all also tracks queries inside functions and stored procedures, which will likely increase the number of rows, and remember there’s no correlation between those non-top-level queries and the top-level function that called them. Setting it to none turns off tracking while leaving the extension loaded. That last option is a handy shortcut: if pg_stat_statements is causing locking issues because of churn, you can reload with none to stop tracking for a while and get relief.

track_utility

This can also be changed with a reload, no restart required. It’s on by default, which means pg_stat_statements tracks essentially all statements, including utility statements like PREPARE, commits, and rollbacks. Those individual statements take up space in the table.

If your priority is tracking DML operations (SELECT, INSERT, UPDATE, DELETE, MERGE), you can turn track_utility off and reload to get instant relief, often saving a meaningful number of rows.

track_planning

This can be changed with a reload. It adds planning values to your statements. The default is off, because it incurs additional overhead from the timing work during the planning phase.

save

Like max, this one can only be changed with a restart. It saves the statistics to a file on a normal shutdown so they can be reloaded when the server restarts. The default is on, and that’s almost certainly what you want: after a restart, pg_stat_statements picks up where it left off instead of rebuilding all the statistics over time.

Reducing deallocations through settings

If you’re seeing a lot of deallocations, there are two settings-based levers. The first is to raise pg_stat_statements.max. We often recommend starting at 10,000 rather than the default 5,000, which is usually a good fit for one primary server with one application database; the more databases you have, the fewer slots there are per database, so the setting may need to go higher. Use the 10-minute window to gauge how often deallocations happen relative to your setting, and remember each one drops 5% of max. Once you think you need beyond roughly 50,000 to 100,000 entries, you likely need other mitigation too. The second lever is to turn off track_utility, a good, cheap way to reduce the number of entries while keeping the application-query data you actually want for tuning.

Reducing deallocations in your application

The fix for deallocations is almost never just tuning these values; it’s also about your application. The first thing to look at is query uniqueness, and the biggest culprit is WHERE IN clauses: on Postgres 17 and below, many IN lists of different lengths produce many individual entries in pg_stat_statements, so consider switching to an array value (your ORM may have a helper for this), and watch for queries built through string concatenation, which is another source of unnecessary uniqueness. Second, you can reduce the number of databases per server, since pg_stat_statements.max is server-wide and lots of activity across many databases means they all contend for the same slots; at some point you may need to break off into more servers with fewer databases. And finally, avoid querying with multiple roles unless necessary, since the same SQL statement executed by different roles produces separate entries in pg_stat_statements.

Key takeaways

Deallocations are measurable. The deallocation counter in pg_stat_statements_info tells you how often pg_stat_statements is dropping 5% of the table to make room for new entries.
Use a 10-minute sampling window. No change is healthy; ~10 per window means losing 5% per minute; ~100 means every six seconds; 600+ means roughly every second, with serious locking and data loss.
Know the five settings. max (restart, reserves memory even when tracking is off), track (top/all/none, reload), track_utility (on by default, turn off to drop utility statements), track_planning (off by default, adds overhead), and save (restart, default on, persists stats across restarts).
Settings buy relief, the application fixes the cause. Raising max to 10,000 and turning off track_utility help, but reducing query uniqueness (WHERE IN lists, concatenation), fewer databases per server, and avoiding redundant roles address the root cause.

What’s coming next

In the next episode we’ll dig into high-cardinality workloads specifically, and look at a couple of concrete ways to minimize deallocations and the loss of data over time. We’re getting close to finishing this series on pg_stat_statements, so I hope to see you back for it.

What we discussed in this episode

Postgres in Production Special Series: How pg_stat_statements Decides What to Keep (Part 4)

Ryan Booz — Tue, 02 Jun 2026 12:00:00 GMT

In Part 4 of this special “Postgres in Production” deep dive series, Ryan Booz takes you into the pg_stat_statements source code to show how it decides what to keep when the hash table fills up. There’s a per-query counter you never see in the view, eviction sorts every entry on every deallocation, only completed executions get stored at all, and a higher pg_stat_statements.max is not free.

Share this episode: Click here to share this episode on LinkedIn. Feel free to sign up for our newsletter and subscribe to our YouTube channel.

A quick recap
What the source code reveals
The three values that drive allocation
Only completed executions get stored
The three functions that do the work
The fast path: when the entry already exists
The slow path: when the entry doesn’t exist
Why a larger pg_stat_statements.max is not free
Key takeaways
What’s coming next
What we discussed in this episode

Transcript

A quick recap

In Part 1 we looked at the in-memory hash table that backs pg_stat_statements and the metrics it tracks. In Part 2 we dug into what makes an entry “unique” — the queryid, derived from the structural shape of the query. And in Part 3 we walked through where the query text actually lives: a separate file on disk, sized at 2× the mean query length × pg_stat_statements.max.

This episode is honestly the one I’m most excited about. We’re going to go look at the source code itself — the structs, the functions, the workflow — and answer the question that’s been lurking under everything so far: when the table is full and a new query comes in, what gets kept and what gets dropped?

I’ll warn you upfront that this episode is a little longer than the others. There’s a lot to cover. The good news is the actual source is small: take out the comments and pg_stat_statements is only about 1,800 lines of code. Most of that is defensive — making sure the right things get stored at the right times. The story underneath is honestly pretty simple, once you can see it.

What the source code reveals

When you look at the C structs in the source, you start to see things we’ve already discussed. The hash table key is what you’d expect: user ID, database ID, queryid, and the top-level boolean that says whether the query was a top-level statement or executed inside a function.

The pgssEntry struct holds a counters array. That’s where the metrics live — number of calls, total time, mean time, JIT counters, buffers read, all of it. From Part 3 you’ll also see the offset and length pointing into the external query text file.

Then there’s a shared state struct with a handful of variables that the workers need across processes. One of those, mean_query_length, is going to matter a lot in a minute.

The three values that drive allocation

As I’ve spent more time in this code over the last year, I’ve come up with three things that I think are really necessary to understand about how pg_stat_statements decides what to keep. There’s more going on than just these three, but if you understand these, the rest of the workflow makes sense.

1. pg_stat_statements.max

We’ve talked about this throughout the series and it works exactly as you’d expect. When a brand-new query comes in and we’ve already reached max entries, pg_stat_statements has no other path — it has to deallocate something to make room, and may also have to truncate the external text file before it can store the new entry.

2. The hidden usage counter

This is the one most people don’t know about. Every hash table entry has a per-query usage value stored alongside the regular metrics. It’s not returned in the pg_stat_statements view. You never see it directly. It exists solely to help decide which entries get dropped when deallocation has to run.

It’s incremented by one every time a query finishes executing. Interestingly, the function that does the incrementing is called USAGE_EXEC() and it takes total time as a parameter — but if you read the code, the value being added is statically typed to 1. The total time goes nowhere. There’s actually a note in the source asking whether this is the right approach, or whether time or buffer usage would be a better proxy for “which queries do we want to keep around longest?” That discussion has been ongoing in the community for a while.

The mechanics during deallocation are:

Decrease every entry’s usage by 1%.
Sort all entries by usage.
Drop the bottom 5%.
Increment the deallocation counter.

One interesting observation: while pg_stat_statements is filling up and no deallocation has happened yet, calls and usage will be the same number for every entry — they’re both going up by one per execution. They only diverge after the first deallocation.

3. mean_query_length

This is the mean length of all the query texts currently in the hash table. It’s only updated during deallocation, right before the bottom 5% gets dropped. Once it’s recomputed, pg_stat_statements uses it to decide whether the external text file is now more than twice the expected length. If it is, the file gets rewritten (the “garbage collection” step we’ll cover below).

Only completed executions get stored

Before we go further, one thing worth being absolutely clear on: pg_stat_statements only stores metrics for completed executions. It’s called from the ExecutorEnd hook, after planning and after everything else has run.

That means no aborted or timed-out query metrics are stored. If you have a statement_timeout of 30 seconds and a query hits that timeout after reading hundreds of thousands of buffers, those buffers don’t show up in pg_stat_statements at all. The query effectively didn’t happen, as far as this extension is concerned.

I want to flag this directly because if you ask an AI about pg_stat_statements in mid-2026 it will often tell you the opposite. I queried this recently and got confidently wrong answers. The source is unambiguous: nothing in the code stores metrics for timed-out queries. This is also one of the problems the community is actively trying to solve — how do we get visibility into how often a query is timing out, and how much work it did before it died? Right now, we don’t.

The three functions that do the work

When you actually read the code, there are three primary functions for storing data:

pgss_store() — every completed execution goes through this. It looks up the hash, and if it’s there, just updates the counters. Done.
entry_alloc() — called when the query is new and the entry needs to be allocated in the hash table.
entry_dealloc() — called from inside entry_alloc when the table is full and we need to make room.

Two secondary functions handle the external query text file:

need_gc_qtexts() — checks whether the file is more than 2× expected size and flags that garbage collection is needed.
gc_qtexts() — does the actual garbage collection: rewrites the file with the texts of whatever’s still in the (now smaller) hash table.

The fast path: when the entry already exists

This is the path you want most of your workload to be on. pgss_store() gets called at the end of execution, looks up the queryid in the hash table, finds it, takes a shared lock, updates the counters, and releases all locks. That’s it. It’s fast, it’s cheap, and many backends can do it concurrently.

If you’re in a steady-state workload where pg_stat_statements has captured your common queries and isn’t churning, this is what’s happening for the vast majority of executions.

The slow path: when the entry doesn’t exist

This is where the work piles up. pgss_store() looks up the queryid, doesn’t find it, and now we have to do real work under an exclusive lock:

Switch from shared to exclusive lock.
Check whether the external text file needs garbage collection later.
Check whether we’ve hit pg_stat_statements.max. If yes, deallocate:
- Decrease all usage values by 1% (or 50% for sticky entries).
- Sort every entry by usage.
- Drop the bottom 5%.
- Increment the deallocation counter.
Call entry_alloc(), which searches one more time before allocating — another backend might have inserted the same queryid in the gap between our locks.
If garbage collection was flagged, load the entire query text file into memory, then overwrite it in place (not a copy + delete — pg_stat_statements actually overwrites the file and truncates the tail with a C truncate call).
Allocate the new entry, initialize its counters, write the text into the file, release the exclusive lock.

The longer this path is and the more often you’re on it, the more time your queries spend waiting for the exclusive lock.

Why a larger pg_stat_statements.max is not free

Look at the deallocation step again: every time we deallocate, we sort all entries by usage and drop the bottom 5%. That sort is linear in the number of entries.

If you’ve bumped max from the default 5,000 to 10,000, 50,000, or 100,000 — which is tempting when you’re losing queries to eviction — then every deallocation has to touch and sort that many rows, all under an exclusive lock. You haven’t eliminated the deallocation cost; you’ve made each one more expensive, while still potentially deallocating frequently if your workload’s cardinality is high enough.

There’s a dance here. A higher max reduces deallocation frequency, but each deallocation costs more. A larger external text file means garbage collection rewrites more data when it triggers. If you only allocate more space without addressing the underlying cardinality, you pay the cost somewhere else.

We’ll get into the configuration choices that actually help in the next couple of episodes.

Key takeaways

There’s a hidden per-query usage counter stored alongside the metrics. It’s not in the pg_stat_statements view but it determines which queries get evicted.
Eviction sorts the whole table. Every deallocation decreases all usage values by 1%, sorts every entry, and drops the bottom 5%.
Only completed executions are stored. Aborted and timed-out queries leave no record in pg_stat_statements — regardless of what an AI tells you.
Three primary functions do all the work: pgss_store, entry_alloc, entry_dealloc. The fast path is shared-lock counter updates. The slow path runs deallocation, garbage collection of the external text file, and entry allocation under exclusive lock.
A higher pg_stat_statements.max is not free. The deallocation sort is linear in max, so a bigger table means each eviction touches more rows under exclusive lock.

What’s coming next

Now that we’ve seen how pg_stat_statements decides what to keep, the last couple of episodes turn to what you can actually do about it. We’ll look at the configuration that matters most, what high-cardinality workloads really look like under this allocation/deallocation pressure (and how Postgres 18’s improvements to WHERE IN help), and concrete strategies for using pg_stat_statements safely at scale.

What we discussed in this episode

Postgres in Production Special Series: Where Your Query Text Actually Lives (Part 3)

Ryan Booz — Tue, 19 May 2026 12:00:00 GMT

In Part 3 of this special “Postgres in Production” deep dive series, Ryan Booz walks through where pg_stat_statements actually stores your query text. Spoiler: it’s not in the in-memory hash table you might expect. He covers the file’s location on disk, how it grows, the pointer mechanism that ties hash table entries back to your SQL, the quirky consequence that the same query text can appear multiple times, and why ORM-heavy workloads can balloon this file to hundreds of megabytes.

Share this episode: Click here to share this episode on LinkedIn. Feel free to sign up for our newsletter and subscribe to our YouTube channel.

A quick recap
Where the query text actually lives
Locating the query text file
How the file grows: append-only with a 2× size ceiling
The pointer mechanism: offset and length per entry
A performance note: when the file actually gets read
No memory of previously tracked queries
The rewrite cycle when the file fills up
A real-world size example
Why ORMs make this worse
Key takeaways
What’s coming next
What we discussed in this episode

Transcript

A quick recap

In the first episode, we looked at the in-memory hash table that backs pg_stat_statements and the metrics it tracks. In Part 2, we dug into what actually makes an entry “unique” — the queryid, which is derived from the structure of the query rather than its text, combined with the role, the database, and whether the query was top-level.

That recap matters because of a question I haven’t answered yet: if the hash table is keyed on a structural hash, where does the actual query text live?

Where the query text actually lives

This is the part that surprises most people the first time they hear it. The query text is not stored in the in-memory hash table. It lives in a separate file on disk, inside the Postgres data directory.

The hash table only holds the metrics, the queryid, and a few small bookkeeping fields. When you ask for the query text, Postgres has to go read it from this file.

Locating the query text file

In most installations, the file lives under the global directory inside the Postgres data directory:

$PGDATA/global/pgss_query_texts.stat

In some Docker images and packaged installations, you’ll find it in $PGDATA/pg_stat_tmp/ instead. Either way, the file is there somewhere, and it’s worth poking around once just to see it exists.

How the file grows: append-only with a 2× size ceiling

Two things to know about how this file behaves:

First, it’s append-only for new entries. Every time a brand-new, normalized query shows up in pg_stat_statements, the text of that query gets written to the end of the file.

Second, it has a size ceiling. The file is allowed to grow to roughly twice the mean length of all currently tracked queries, multiplied by the maximum number of entries pg_stat_statements is configured to hold. pg_stat_statements updates the mean query length during deallocation, so it changes over time, before the query file is truncated.

The pointer mechanism: offset and length per entry

The way the hash table and the file stay in sync is straightforward. For every entry in the in-memory hash table, pg_stat_statements stores a pointer into the text file — really, an offset and a length. When you ask for the query text, Postgres opens the file, seeks to the offset, reads that many bytes, and hands you back the SQL.

The file is otherwise hidden from you. You’ll never interact with it directly. But understanding that the pointer dance is happening explains a few quirks you’ll see in production.

A performance note: when the file actually gets read

Because reading the file is a real I/O operation, pg_stat_statements is careful about when it opens it.

If you call the function form, pg_stat_statements(true), you’ll get the query text in the results. Pass false instead and pg_stat_statements skips the file entirely:

-- Reads the on-disk text file:
SELECT * FROM pg_stat_statements(true);

-- Does not read the file:
SELECT * FROM pg_stat_statements(false);

Unfortunately the same does not apply to the view. Regardless of whether or not you select the query column, the view always opens the query text file and retrieves the query text. On a busy system where you’re just charting metrics, using pg_stat_statements(false) is a good habit to get into, only retrieving query texts when necessary.

No memory of previously tracked queries

Here’s the quirky consequence of the pointer mechanism. pg_stat_statements has no memory of previously tracked queryids.

Say your pg_stat_statements.max is 5,000 and you fill it. A new query comes in, an old one gets evicted, and the evicted entry’s metrics are gone. Now imagine that same evicted query runs again later. As far as the in-memory hash table is concerned, this is a brand-new entry. Postgres writes the text to the file again, at a fresh offset, with a fresh pointer.

The practical result: the same query text can appear multiple times in the file. It’s not a bug, it’s a direct consequence of the hash table not remembering what it has evicted.

The rewrite cycle when the file fills up

When the file hits its size ceiling, pg_stat_statements doesn’t garbage-collect in place. Instead, it rewrites the entire file based on what’s currently active in the hash table, writes that to a temporary file, drops the old file, and renames the temp file into its place.

There’s a brief moment of locking during the swap. On a small file that’s invisible. On a large file, it isn’t.

A real-world size example

This file can grow more than you’d expect. As a quick illustration, I checked a local instance with pg_stat_statements.max = 5000:

About 5,000 currently tracked queries
Mean query text length: about 900 bytes

That works out to roughly 5000 × 900 × 2 ≈ 9 MB before pg_stat_statements rewrites the file. That’s modest.

But the multipliers run away on you fast. Raise max to 20,000 or 50,000, or work with a system that generates very long SQL on average, and the file can comfortably reach hundreds of megabytes. At that scale, the rewrite cycle is a real disk and lock event, not a footnote.

Why ORMs make this worse

ORMs are the most common reason a real-world pgss_query_texts.stat blows up.

ORMs don’t optimize for the structural shape of the SQL they emit. They optimize for translating your application code into something Postgres can parse. The result is verbose, comment-laden, sometimes deeply nested SQL — and the texts are long. When the mean query length on your system is 8,000 bytes instead of 900, the size ceiling for the text file shifts by an order of magnitude.

Combined with the high cardinality problem from Part 2 (where ORMs create lots of distinct queryids), this is the worst-case profile: many entries, each one large, file at its maximum size, frequent rewrites under lock.

If you’re seeing intermittent latency spikes on a system with a heavy ORM workload and a large pg_stat_statements.max, this is worth a look.

Key takeaways

The query text isn’t in the hash table. It’s in a separate file on disk in the Postgres data directory.
Each hash table entry holds a pointer (offset + length) into that file, not the text itself.
The file is append-only for new entries, and grows to roughly 2× the mean query length × pg_stat_statements.max.
pg_stat_statements has no memory of previously evicted queryids. Evicted queries that come back are treated as new, and their text gets written to the file again. The same text can appear multiple times.
When the file hits its size ceiling, Postgres rewrites it from scratch. A temp file gets written, the old file is dropped, the temp is renamed in. There’s a brief moment of locking during the swap.
ORM-heavy workloads are the most common reason the file balloons. Long SQL × many distinct queryids = a large file and frequent rewrites.
Reading the file is optional. pg_stat_statements(false) skips reading the file from disk.

What’s coming next

Now that we’ve covered where the query text lives, the next episode takes us to the Postgres source. We’ll look at how pg_stat_statements.max is enforced, how the 2× file size ceiling is implemented, what eviction actually does, and what gets kept when entries are evicted. That’s where the practical “is the data I need actually still in pg_stat_statements?” question gets answered.

What we discussed in this episode

Postgres in Production Special Series: What Makes a Statement Unique (Part 2)

Ryan Booz — Wed, 06 May 2026 12:00:00 GMT

In Part 2 of this special “Postgres in Production” deep dive series, Ryan Booz walks through what actually makes an entry in pg_stat_statements “unique”, why uniqueness is structural rather than textual, and how a few common patterns (ORMs, dynamic SQL, multi-database setups) can quietly fill up the in-memory hash table and cost you visibility into the queries that matter most.

Share this episode: Click here to share this episode on LinkedIn. Feel free to sign up for our newsletter and subscribe to our YouTube channel.

A quick recap
What makes an entry unique
A note on top-level queries
How quickly entries multiply
Uniqueness is structural, not textual
What gets normalized away
Why SQL comment tags can disappear
What doesn’t get normalized
The IN-clause explosion (and how Postgres 18 fixes it)
Structure vs. semantics
What happens when pg_stat_statements fills up
Key takeaways
What’s coming next
What we discussed in this episode

Transcript

A quick recap

In the first episode, we looked at the in-memory hash table that backs pg_stat_statements and the columns it exposes — about 45 of them in Postgres 18, with more likely to come in future versions. In this episode, we dig into what actually makes an entry in that table “unique”, and why getting that wrong can quietly cost you visibility into your most important queries.

What makes an entry unique

Each entry in pg_stat_statements is keyed on four things:

The role that ran the query
The database it ran in
The queryid, a hash derived from the structure of the query
Whether the query was top-level

That last one deserves a brief explanation, because it’s controlled by a setting that’s easy to miss.

A note on top-level queries

By default, pg_stat_statements.track is set to top. A top-level query is the one you initiated directly from a session or transaction. For example, running SELECT title FROM ... from your application is a top-level query.

If that query in turn triggers other queries, typically by calling a function or stored procedure, those internal queries are not top-level. They were initiated by Postgres on your behalf, not by you.

With the default setting, you’ll see the function call itself in pg_stat_statements, but not the queries it runs internally. If you change the setting to all, those internal statements get tracked too. The catch: there is no column anywhere in pg_stat_statements that ties an internal statement back to the parent that called it. You can see the metrics, but you can’t reconstruct the call chain. As of Postgres 18, that’s a known limitation, and nothing on the horizon for 19 or beyond changes it.

How quickly entries multiply

Even a simple workload can produce a surprising number of entries. Imagine a single query, SELECT title FROM film WHERE id = ?. Now imagine running it across:

Three databases on the same server (for example, one per customer, all with the same schema)
A handful of roles per database

You’ll get one entry per (role, database, queryid) combination. In a setup with three databases, three users, and one application user running the query in each database, you can land at five entries from a single logical query. Change the SELECT clause to SELECT title, rating FROM film WHERE id = ? and you get a brand-new queryid, doubling the count to ten.

Now scale that up across an ORM that emits dozens of variants of every query, and you can see how the entry count climbs fast.

This matters because pg_stat_statements has a hard ceiling. The pg_stat_statements.max setting controls how many unique entries it will track at once, and the default is 5,000. You can raise or lower it, but at any moment in time, that’s the upper limit. If you go over, something has to be evicted.

Uniqueness is structural, not textual

This is the part most people get wrong, myself included. The instinctive assumption is that uniqueness is based on the query text, what you wrote or what your ORM generated. It’s not. It’s based on the query’s structure.

Postgres parses the query, walks the parse tree, strips out things that don’t affect the structure (like literal values), serializes what’s left, and hashes the result. That hash is the queryid.

The internal name for this process is jumbling, handled by a function called JumbleQuery(). You’ll hear the term in mailing list discussions and in the source code, so it’s worth knowing.

The practical upshot: this query, run with three different parameter values:

SELECT title FROM film WHERE id = 1;
SELECT title FROM film WHERE id = 2;
SELECT title FROM film WHERE id = 3;

produces a single entry in pg_stat_statements. You could run it a thousand times with a thousand different IDs and you’d still get one entry.

What gets normalized away

Anything that doesn’t change the shape of the query gets normalized:

Literals and constants (numbers, strings, dates)
Parameter values
Whitespace and formatting
Comments

That last one trips people up. A common pattern is to inject comments into queries to track which application function generated them, something like /* user_service.fetch_profile */ SELECT .... Comments are stripped during jumbling, so two structurally identical queries with different comments collapse into one entry.

There’s a subtle quirk here: when an entry is first created, pg_stat_statements stores the exact text of the first execution it saw. Every subsequent execution with the same queryid contributes its metrics to that entry, but the stored text doesn’t change. So if your first execution happened to carry one comment and the next thousand carried different ones, the view will only ever show you that first comment. The metrics are accurate; the text is misleading.

Why SQL comment tags can disappear

The same thing applies to SQLcommenter-style tags, which ORMs and observability tools often use to attach metadata (route, controller, feature flag) to a query. They’re just comments, so jumbling treats them the same way.

I see this come up regularly: a customer is staring at an OpenTelemetry span with a SQLcommenter tag, trying to find the matching execution in pg_stat_statements, and they can’t. The tag they’re looking for isn’t in the stored text, because some other execution (with a different tag, or no tag at all) got there first.

What doesn’t get normalized

Anything that affects the structure of the query does affect the queryid:

The number of columns selected
The number of items in an IN list
ORDER BY clauses
JOIN structure
The number of WHERE conditions

Take a long, complex query with multiple CTEs. If the only thing that changes between executions is the set of WHERE conditions at the end, each variant gets its own entry.

The IN-clause explosion (and how Postgres 18 fixes it)

This one is worth singling out, because it’s a common foot-gun and it explains a lot of “why is my pg_stat_statements full?” investigations.

In Postgres 17 and below, every distinct length of an IN list produces a unique queryid:

SELECT * FROM film WHERE id IN (1);
SELECT * FROM film WHERE id IN (1, 2);
SELECT * FROM film WHERE id IN (1, 2, 3);
-- ... and so on

If your ORM cheerfully sends IN lists of every possible length, you can blow through hundreds of entries from a single logical query.

Postgres 18 finally fixes this. It rewrites WHERE id IN (1, 2, 3) into WHERE id = ANY('{1, 2, 3}'), which is structurally a single query regardless of the array length. The result: one entry in pg_stat_statements no matter how many values you pass. If you’ve ever stared at a pg_stat_statements view that was 90% IN-clause variants, this alone is a strong reason to look at upgrading.

Structure vs. semantics

It’s tempting to assume that semantically equivalent queries get the same queryid. They don’t. pg_stat_statements cares about structure, not meaning.

These two queries produce identical query plans:

SELECT * FROM film WHERE film_id = 557;
SELECT * FROM film WHERE 557 = film_id;

But they’re structurally different, so they’re two entries. The same goes for:

SELECT * FROM film WHERE film_id IN (1, 2, 3);
SELECT * FROM film WHERE film_id = ANY('{1, 2, 3}');

Logically and operationally identical. Two entries.

What happens when pg_stat_statements fills up

This is the reason any of this matters. When the number of tracked entries hits pg_stat_statements.max, the next new query coming along has to displace something. Postgres deallocates an existing entry, and the metrics for that query are gone until the query runs again and a fresh entry gets created.

Raising pg_stat_statements.max helps, but it’s not a fix. If your workload is generating thousands of unintentionally unique queries, you’ll fill up whatever ceiling you set. The better move is to understand where the structural variation is coming from and reduce it at the source.

Key takeaways

High cardinality is the enemy. Every unique queryid eats a slot, and slots are finite.
ORMs are a major source of cardinality. Different argument shapes, optional clauses, and dynamic column lists all create new queryids.
Dynamic SQL has the same problem. If you build queries by string concatenation, every variation is its own entry.
Multi-database and multi-role setups multiply everything. pg_stat_statements is per-instance, but its key includes role and database.
Eviction is silent. You won’t get an error or a warning. Entries just disappear, and so do their metrics.

What’s coming next

Now that we’ve covered what makes an entry unique, the next episode looks at where the query text itself is actually stored. Quick spoiler: it’s not in the in-memory hash table, and the way Postgres handles it has real consequences for how reliably you can identify queries after the fact. We’ll dig into that in Part 3.

What we discussed in this episode

Postgres in Production Special Series: What pg_stat_statements Is and Isn't (Part 1)

Ryan Booz — Mon, 13 Apr 2026 12:00:00 GMT

In this special series of “Postgres in Production”, we take a deep dive into pg_stat_statements — the essential Postgres extension for tracking query performance. In Part 1, Ryan Booz covers what pg_stat_statements is, how to enable it, what it tracks, and critically, what it doesn’t track and why that matters for your monitoring setup.

Share this episode: Click here to share this episode on LinkedIn. Feel free to sign up for our newsletter and subscribe to our YouTube channel.

What is pg_stat_statements?
How pg_stat_statements stores data
Enabling pg_stat_statements
What does it track?
The cumulative metrics problem
What it doesn’t track
Why this matters for monitoring
What’s coming in this series
What we discussed in this episode

Transcript

What is pg_stat_statements?

Have you ever found yourself asking questions like: “My database is slow right now — which query is using all the resources?” Or maybe, “Over the last 24 hours, which queries on average take more than a second to execute?” What about, “Some of these webpages are loading slowly — can you show me which queries are called a lot, but take a couple hundred milliseconds on average?”

These are common questions for database engineers, DBAs, and developers trying to make their applications work well with Postgres. And the answer has almost always been: go use pg_stat_statements.

pg_stat_statements is an included extension, part of the contrib modules that ship with the Postgres open source project. It’s available wherever you install Postgres — whether that’s a cloud provider, a Docker container, or a bare metal install. It’s there, it just needs to be activated.

How pg_stat_statements stores data

The metrics that pg_stat_statements holds are stored in an in-memory hash table per Postgres instance — not per database. There’s one instance of this hash table across all databases within a Postgres instance, and it tracks per-execution query metrics.

Enabling pg_stat_statements

To enable pg_stat_statements, two steps are required:

Configure it within the shared_preload_libraries setting in postgresql.conf. If you’re using a cloud environment, some providers enable this by default, and all give you a way to edit this setting.
Install the extension on at least one database using the CREATE EXTENSION command.

Once that’s done, you can begin querying the data.

What does it track?

As of Postgres 18, there are at least 45 columns in this view, including:

A unique query ID for every normalized query text
The actual query text
Call counts, total time, and mean run time
Rows selected
Lock and block information
Planning metrics

There’s a lot of data, and it can be incredibly helpful for finding queries that need your attention.

The cumulative metrics problem

One of the key things to understand is that all metrics in pg_stat_statements are cumulative — but only since the last time a query was tracked.

Up until recently, the common understanding was that metrics persist until the server restarts or until you explicitly reset them with pg_stat_statements_reset(). For years, the workflow looked like this:

Server is slow? Run pg_stat_statements_reset() to clear all metrics
Wait a few minutes, then query the view to find which queries are using the most resources
Identify and optimize the problematic query
Reset metrics again and continue monitoring

pg_stat_statements wasn’t originally intended to be sampled over and over for days, weeks, or months to track long-term query metric performance.

This was an aha moment — many of us assumed that if a query has run at any point during the lifetime of a Postgres instance, there would be data for it in pg_stat_statements. That’s just not true.

What it doesn’t track

At a high level, pg_stat_statements does not provide:

Per-execution history — There’s no record saying “this query was executed two months ago and here are the metrics for that specific execution”
Time-windowed data — It’s not a per-second or per-minute view. Monitoring tools have to calculate deltas from the cumulative metrics themselves
Every query forever — At any one time, it can only track up to pg_stat_statements.max unique query texts (default: 5,000)

The real issue is what happens when it reaches that 5,000 unique query limit — something we’ll explore in depth throughout this series.

Why this matters for monitoring

When we treat pg_stat_statements as the single source of truth for query performance history, we run into real problems:

Every monitoring tool that tracks query performance over time samples from pg_stat_statements — it’s the only query metrics view available everywhere in Postgres
If you don’t understand when pg_stat_statements can fail or when settings need to be modified, you could be flying blind when it matters most
You might not be able to find a problematic query or its historical data in either pg_stat_statements or your monitoring tool

What’s coming in this series

Over the next episodes in this series, we’ll cover:

What makes a “unique” statement — How normalized query texts work, and what “normalize” really means
Source code deep dive — Uncovering misconceptions by looking at the actual Postgres source
Query text truncation — Why you can’t always find the full query text
Configuration tuning — How to better configure pg_stat_statements for your workload
High cardinality workloads — Why they’re problematic and what you can do about it
Long-term strategies — Better ways to utilize pg_stat_statements as your Postgres environment grows

Stay tuned for Part 2, where we’ll dig into what makes a statement “unique” in pg_stat_statements and look at the source code to uncover some longstanding misconceptions.

pganalyze Blog - Articles by Ryan Booz

Postgres in Production Special Series: Diagnosing High Cardinality Workloads in pg_stat_statements (Part 6)

A quick recap

What a high cardinality workload means

Where the unique queries come from

A demo: overwhelming pg_stat_statements with Bluebox

Our databases are hidden behind our tools

How to tell if you have a high cardinality workload

Taking action

What happens if you don’t

Key takeaways

What’s coming next

What we discussed

Postgres in Production Special Series: Configuring pg_stat_statements to Reduce Deallocations (Part 5)

A quick recap

Why deallocations matter

Seeing deallocations: the pg_stat_statements_info view

Sampling the deallocation counter (the 10-minute window)

What the deallocation numbers mean

The configuration settings

pg_stat_statements.max

pg_stat_statements.track

track_utility

track_planning

save

Reducing deallocations through settings

Reducing deallocations in your application

Key takeaways

What’s coming next

What we discussed in this episode

Postgres in Production Special Series: How pg_stat_statements Decides What to Keep (Part 4)

A quick recap

What the source code reveals

The three values that drive allocation

1. pg_stat_statements.max

2. The hidden usage counter

3. mean_query_length

Only completed executions get stored

The three functions that do the work

The fast path: when the entry already exists

The slow path: when the entry doesn’t exist

Why a larger pg_stat_statements.max is not free

Key takeaways

What’s coming next

What we discussed in this episode

Postgres in Production Special Series: Where Your Query Text Actually Lives (Part 3)

A quick recap

Where the query text actually lives

Locating the query text file

How the file grows: append-only with a 2× size ceiling

The pointer mechanism: offset and length per entry

A performance note: when the file actually gets read

No memory of previously tracked queries

The rewrite cycle when the file fills up

A real-world size example

Why ORMs make this worse

Key takeaways

What’s coming next

What we discussed in this episode

Postgres in Production Special Series: What Makes a Statement Unique (Part 2)

A quick recap

What makes an entry unique

A note on top-level queries

How quickly entries multiply

Uniqueness is structural, not textual

What gets normalized away

Why SQL comment tags can disappear

What doesn’t get normalized

The IN-clause explosion (and how Postgres 18 fixes it)

Structure vs. semantics

What happens when pg_stat_statements fills up

Key takeaways

What’s coming next

What we discussed in this episode

Postgres in Production Special Series: What pg_stat_statements Is and Isn't (Part 1)

What is pg_stat_statements?

How pg_stat_statements stores data

Enabling pg_stat_statements

What does it track?

The cumulative metrics problem

A demo: overwhelming `pg_stat_statements` with Bluebox