The inspect command runs a set of read-only diagnostic queries against a branch's Postgres and prints the results. Each query targets a common operational question, such as which tables are largest, which indexes go unused, what is holding locks, or how the cache is performing. Nothing is modified, so the command is safe to run against any branch.
Subcommands: db
neon inspect db
Run a single diagnostic query against a branch's Postgres. Pick the query with a subcommand, for example neon inspect db table-sizes.
neon inspect db <sub-command> [options]By default the command resolves the project, branch, database, and role from your context and connects through the Neon API. Pass --db-url to inspect any Postgres directly from a connection string, which bypasses API resolution and lets you point inspect at a database outside Neon.
Some queries read from Postgres statistics extensions. outliers and calls need pg_stat_statements, and lfc-hit-rate and working-set need the neon extension. If a required extension is not installed, the command reports it instead of returning rows.
Subcommands: bloat, calls, index-sizes, lfc-hit-rate, locks, long-running-queries, outliers, replication-slots, seq-scans, subscriptions, table-sizes, unused-indexes, vacuum-stats, working-set
neon inspect db table-sizes
Size of each table, including TOAST, largest first.
neon inspect db table-sizes┌────────┬───────────┬─────────┐
│ Schema │ Name │ Size │
├────────┼───────────┼─────────┤
│ public │ events │ 16 MB │
├────────┼───────────┼─────────┤
│ public │ orders │ 4752 kB │
├────────┼───────────┼─────────┤
│ public │ customers │ 1616 kB │
└────────┴───────────┴─────────┘neon inspect db index-sizes
Size of each index, largest first.
neon inspect db index-sizesneon inspect db unused-indexes
Non-unique, non-primary-key indexes with fewer than 50 scans, largest first. These are candidates for removal. Check the Index Scans column: an index that has never been scanned (0) while taking up space is a strong candidate to drop.
neon inspect db unused-indexes┌──────────────────┬────────────────────────┬────────────┬─────────────┐
│ Table │ Index │ Index Size │ Index Scans │
├──────────────────┼────────────────────────┼────────────┼─────────────┤
│ public.events │ events_created_at_idx │ 1368 kB │ 0 │
├──────────────────┼────────────────────────┼────────────┼─────────────┤
│ public.orders │ orders_customer_id_idx │ 1024 kB │ 2 │
├──────────────────┼────────────────────────┼────────────┼─────────────┤
│ public.customers │ customers_email_idx │ 808 kB │ 0 │
├──────────────────┼────────────────────────┼────────────┼─────────────┤
│ public.orders │ orders_status_idx │ 560 kB │ 20 │
└──────────────────┴────────────────────────┴────────────┴─────────────┘neon inspect db seq-scans
Number of sequential scans recorded against each table, highest first. A high count on a large table often points to a missing index.
neon inspect db seq-scansneon inspect db long-running-queries
Queries that have been running longer than five minutes. Run it to catch a runaway statement. When nothing qualifies, it says so instead of printing an empty table:
neon inspect db long-running-queriesNo long-running queries.neon inspect db locks
Locks currently held, with the query that acquired each one and its age. When writes are blocked, run this to find what is holding the lock.
neon inspect db locksNo locks held.neon inspect db outliers
The top 25 queries by cumulative execution time (Total Exec Time), with each query's share of the total (Prop Exec Time) and how often it ran (Ncalls). This ranks by total time spent, so a cheap query that runs constantly can outrank an expensive one that runs rarely. Needs the pg_stat_statements extension.
neon inspect db outliersShow output
┌─────────────────┬────────────────┬────────┬───────────────────────────────────────────────────────────────────────┐
│ Total Exec Time │ Prop Exec Time │ Ncalls │ Query │
├─────────────────┼────────────────┼────────┼───────────────────────────────────────────────────────────────────────┤
│ 00:00:00.875831 │ 57.0% │ 250 │ SELECT * FROM orders WHERE customer_id = $1 │
├─────────────────┼────────────────┼────────┼───────────────────────────────────────────────────────────────────────┤
│ 00:00:00.439406 │ 28.6% │ 400 │ SELECT * FROM customers WHERE email = $1 │
├─────────────────┼────────────────┼────────┼───────────────────────────────────────────────────────────────────────┤
│ 00:00:00.220669 │ 14.4% │ 15 │ SELECT status, count(*), sum(total_cents) FROM orders GROUP BY status │
└─────────────────┴────────────────┴────────┴───────────────────────────────────────────────────────────────────────┘neon inspect db calls
The top 25 queries by call count (Ncalls). Where outliers ranks by total time, this ranks by how often a query runs, so it highlights hot paths worth caching or batching even when each individual call is cheap. Needs the pg_stat_statements extension.
neon inspect db callsShow output
┌────────┬─────────────────┬────────────────┬───────────────────────────────────────────────────────────────────────┐
│ Ncalls │ Total Exec Time │ Prop Exec Time │ Query │
├────────┼─────────────────┼────────────────┼───────────────────────────────────────────────────────────────────────┤
│ 400 │ 00:00:00.439406 │ 59.8% │ SELECT * FROM customers WHERE email = $1 │
├────────┼─────────────────┼────────────────┼───────────────────────────────────────────────────────────────────────┤
│ 250 │ 00:00:00.875831 │ 37.4% │ SELECT * FROM orders WHERE customer_id = $1 │
├────────┼─────────────────┼────────────────┼───────────────────────────────────────────────────────────────────────┤
│ 15 │ 00:00:00.220669 │ 2.2% │ SELECT status, count(*), sum(total_cents) FROM orders GROUP BY status │
└────────┴─────────────────┴────────────────┴───────────────────────────────────────────────────────────────────────┘neon inspect db lfc-hit-rate
Compute cache hit rate, the share of reads served from your compute's cache instead of storage. A low or falling ratio means your working set no longer fits in the cache. Read it after the compute has handled some traffic, not on a freshly resumed one. Needs the neon extension.
neon inspect db lfc-hit-rateneon inspect db working-set
Estimated working set size over several time windows, compared with the compute cache size. When Exceeds Lfc is no, your recent data fits in cache. A yes means the working set has outgrown the cache, and a larger compute may help. Needs the neon extension.
neon inspect db working-set┌────────┬─────────────┬──────────┬─────────────┐
│ Window │ Working Set │ Lfc Size │ Exceeds Lfc │
├────────┼─────────────┼──────────┼─────────────┤
│ 1m │ 48 MB │ 607 MB │ no │
├────────┼─────────────┼──────────┼─────────────┤
│ 5m │ 48 MB │ 607 MB │ no │
├────────┼─────────────┼──────────┼─────────────┤
│ 15m │ 48 MB │ 607 MB │ no │
├────────┼─────────────┼──────────┼─────────────┤
│ 1h │ 48 MB │ 607 MB │ no │
└────────┴─────────────┴──────────┴─────────────┘neon inspect db vacuum-stats
Autovacuum status per table: last (auto)vacuum time, dead tuples, and the autovacuum threshold, ordered by dead tuples. Rising dead tuples with no recent autovacuum points at autovacuum falling behind.
neon inspect db vacuum-statsVacuum stats reset on auto-suspend
Postgres resets these counters whenever the compute restarts, including after a scale-to-zero auto-suspend. On a freshly resumed compute they start near empty, so read them after the database has handled some real traffic.
neon inspect db bloat
The top 25 tables by estimated wasted bytes. It needs no extension. The number is a statistical estimate, so use it to decide where to look, not as an exact measurement.
neon inspect db bloatneon inspect db replication-slots
Replication slots with their kind, status, client, restart and confirmed-flush LSNs, and lag. Check the lag and status columns to see how far each replica or subscriber is behind the primary.
neon inspect db replication-slotsneon inspect db subscriptions
Per-table logical replication progress on this subscriber. Run it on a database with a subscription to see which tables are still copying and which have caught up. On other databases it reports that no subscriptions were found.
neon inspect db subscriptions