Inspect the database

This guide explains how to read live database statistics using the CLI, MCP, or Explorer.

Read database statistics from:

• Studio: Explorer with query source Database
• MCP: execute_sql
• CLI: supabase inspect db

Use this page to:

• Run CLI inspection commands
• Run SQL checks

To pick up a signal from these checks, see Detecting. For the other sources, see Observability.

Using the CLI#

The Supabase CLI reads live statistics from Postgres internals. Most commands work on any Postgres database, not only a Supabase project.

The inspect db command#

The inspection tools for your Postgres database are under the inspect db command. You can get a full list of available commands by running supabase inspect db help.

1
$ supabase inspect db help
2
Tools to inspect your Supabase database
3
4
Usage:
5
  supabase inspect db [command]
6
7
Available Commands:
8
  bloat                Estimates space allocated to a relation that is full of dead tuples
9
  blocking             Show queries that are holding locks and the queries that are waiting for them to be released
10
  cache-hit            Show cache hit rates for tables and indices
11
12
...

Connect to any Postgres database#

Most inspection commands are Postgres agnostic. You can run inspection routines on any Postgres database even if it is not a Supabase project by providing a connection string via --db-url.

For example you can connect to your local Postgres instance:

1
supabase inspect db bloat --db-url postgresql://postgres:postgres@localhost:5432/postgres

Connect to a Supabase instance#

Working with Supabase, you can link the Supabase CLI with your project:

1
supabase link --project-ref <project-id>

Then the CLI will automatically connect to your Supabase project whenever you are in the project folder and you no longer need to provide --db-url.

Inspection commands#

Below are the db inspection commands provided, grouped by different use cases.

Disk storage#

These commands are handy if you are running low on disk storage:

• bloat - estimates the amount of wasted space
• vacuum-stats - gives information on waste collection routines
• table-record-counts - estimates the number of records per table
• table-sizes - shows the sizes of tables
• index-sizes - shows the sizes of individual index
• table-index-sizes - shows the sizes of indexes for each table

Query performance#

The commands below are useful if your Postgres database consumes a lot of resources like CPU, RAM or Disk IO. You can also use them to investigate slow queries.

• cache-hit - shows how efficient your cache usage is overall
• unused-indexes - shows indexes with low index scans
• index-usage - shows information about the efficiency of indexes
• seq-scans - show number of sequential scans recorded against all tables
• long-running-queries - shows long running queries that are executing right now
• outliers - shows queries with high execution time but low call count and queries with high proportion of execution time spent on synchronous I/O

Locks#

• locks - shows statements which have taken out an exclusive lock on a relation
• blocking - shows statements that are waiting for locks to be released

Connections#

• role-connections - shows number of active connections for all database roles (Supabase-specific command)
• replication-slots - shows information about replication slots on the database

Using SQL#

Open Explorer, select Run SQL, and choose Database as the query source. You can also run read-only diagnostics through MCP execute_sql.

Use Performance checks for active sessions, blockers, expensive statements, and cache hit rates. Use Capacity checks for relation sizes and connection counts.

pg_stat_activity is a live snapshot. pg_stat_statements and cache counters are cumulative since their last reset; they do not describe an arbitrary historical window. Compare saved snapshots with the same reset interval when measuring changes. Check the pg_stat_statements guide for extension requirements.

When a check identifies a statement, inspect its query plan. A long-running session or high cumulative query time is evidence to investigate, not a reason by itself to cancel a query or reset statistics.