The tool is PgLens, a Postgres index advisor I’m building. Like several other advisors, it checks each suggestion with HypoPG: create a hypothetical index, run EXPLAIN again, and keep the suggestion if the planner’s estimated cost drops by at least 15%.

That’s an estimate, not a timing. So I built every index for real and timed the queries.

The setup

• The Join Order Benchmark: 113 queries over the real IMDB data, 7 GB loaded. It was made to catch the planner getting row counts wrong, so it’s a hard test.
• PostgreSQL 16, hypopg 1.4.
• PgLens made 214 planner-validated recommendations for those queries. They name only 10 distinct indexes, because one foreign-key index helps many queries.
• I wrote down the metrics and what counts as a win before the first run: 15% faster is a win, 5% slower is a loss.

What happened

• 128 of 179 made their query at least 15% faster.
• 32 of 179 made it at least 5% slower. 7 made it more than twice as slow.
• 34 couldn’t be measured, because the index can’t be built.

The worst one was query 10c with an index on cast_info (movie_id). Estimated: 91% cheaper. Measured: 0.93 s before, 7.3 s after. I ran it again by hand to be sure: about 1 s became about 9 s.

With the index there, the planner picked a nested loop that probes cast_info once per row of a join. It underestimated how many rows that join returns, so the loop ran far more often than it planned for: the query read 71 times as many buffers. HypoPG can’t catch this, because it asks the same planner with the same wrong row counts. Every advisor built on hypothetical indexes has this blind spot, mine included.

The 34 are one index, PgLens’s #2 suggestion, movie_info (info):

ERROR:  index row requires 9392 bytes, maximum size is 8191

1,182 of 14.8 million values are too long for a B-tree entry. A hypothetical index never writes an entry, so it can’t know.

What the planner got right

The ranking. PgLens’s #1 index saved 364 s of the 424 s its queries took, and the order of the indexes by estimated saving was close to the order by measured saving (Spearman 0.83). Per query, the estimated percentage told me almost nothing.

So “which index matters most?” is a fair question for the planner. “How much faster will this query get?” isn’t.

What I changed

• Every planner number in PgLens is labelled as an estimate, and never shown as a speedup.
• pglens confirm builds the index on a copy of your database and times your own queries with and without it. On the same data it flagged 10c as about ten times slower.
• Once you build an index, PgLens shows each query’s measured time before and after.
• It now warns when an index’s column may hold values too long for a B-tree.

Try it

PgLens is open source (Apache-2.0), self-hosted, and only ever reads from your database. It ranks your queries by the time they actually took, suggests a planner-checked index for each, lets you time it on a copy first, and shows the measured before and after once you build it. Four make commands from the README start a demo with a slow workload in about three minutes: github.com/Prateek-Arora/pglens. It’s a release candidate, so bug reports are very welcome.

The method, the tables and the scripts are in docs/benchmarks.md, and make accuracy-job reruns the whole thing. If you run pglens confirm on a copy of your own database, I’d like to see the numbers, especially the ones that make my tool look bad.

I built PgLens with Claude Code as a pair. The benchmark design, the rules written down before the run, and every raw number are in the repo, so you don’t have to take my word for any of it.

The tool is PgLens, a Postgres index advisor I’m building. It only needs to read, so it logs in as a role with no write grants, and it used to start every connection with:

SET SESSION CHARACTERISTICS AS TRANSACTION READ ONLY;

Before the first release I wanted to see what happens if someone points it at a connection pooler, like Supabase’s port 6543 or a Neon -pooler host. So I tried it with PgBouncer in transaction mode. PgLens connected, then the application connected and tried to write:

CREATE TABLE orders_archive (id int);
ERROR:  cannot execute CREATE TABLE in a read-only transaction

The app did nothing wrong. It just got the connection PgLens had used a moment earlier. Not great for a tool whose whole pitch is that it’s safe to point at production.

Why

A transaction pooler hands the same server connection to the next client. Session settings stay on that connection, so my SET went with it.

PgBouncer’s docs do say session SET doesn’t work in transaction mode. I read that as: your setting might not stick. It sticks, just for the wrong client.

The fix

Don’t set anything on the session. Pass the guards as startup options instead, which last only as long as that backend:

options=-c default_transaction_read_only=on -c statement_timeout=30s -c lock_timeout=5s

PgBouncer refuses them (unsupported startup parameter in options), which is what I want: PgLens stops and tells you to connect directly.

Since poolers can be configured to ignore that, PgLens also checks on connect that the backend pid stays the same and read-only is on. An integration test runs it against a real PgBouncer.

If you build tools that connect to other people’s databases

• Don’t SET anything on a connection unless you know it goes straight to Postgres.
• Put guards in startup options, and check they took effect.
• Test against a transaction-mode pooler. Some of your users are behind one.

The alternatives I rejected are in ADR-0053.

Update, 1 Oct: PgBouncer 1.26.0, out on 23 September, now tracks default_transaction_read_only on Postgres 14 and later, so this exact leak is fixed there. Settings it doesn’t track, like statement_timeout, still leak. It also tells the client its pool mode at login, so a tool can allow session mode and refuse only transaction mode.