pg-checkup
Workspace
HomeReports
GitHub
Run on GitHub
Learn
OverviewQuickstartChecks referenceTables that never clean themselvesConnectingRun it on your machineMigration checksTools that helpSecurity & privacyFAQ
Help
File a ticketRequest a featurePricing
PrivacyTerms
Docs/Quickstart
Sign inNew checkupC

Quickstart

1. Optional: create a read-only role

Any login works, so you can skip this and use the one you have. A dedicated role limits what a leaked connection string can do. Connect as an admin and run:

create role checkup_reader login password 'choose-a-strong-password';
grant pg_monitor to checkup_reader;
-- Some hosts keep extensions in their own schema (Supabase: "extensions"). This grants usage only if that schema exists.
do $$ begin if exists (select 1 from pg_namespace where nspname = 'extensions') then execute 'grant usage on schema extensions to checkup_reader'; end if; end $$;

Any name works except one starting with pg_, which Postgres reserves. pg_monitor is a built-in Postgres role that can read statistics views (pg_stat_activity, pg_stat_statements, and so on). It cannot read your table data and cannot write.

2. (Recommended) enable pg_stat_statements

Query-level findings need this extension.

create extension if not exists pg_stat_statements;

On self-managed Postgres you must also add pg_stat_statements to shared_preload_libraries and restart. Managed hosts usually preload it; see Connecting.

3. Run the check

Open /scan, paste postgres://checkup_reader:password@host:5432/dbname and press Run checkup. A scan takes a few seconds.

What you get

The report is a console for your database, with a sidebar listing each area we inspected: Queries, Tables, Indexes, Blocked transactions, Connections, Replication & WAL, Vacuum & bloat, Configuration, Logs & activity, Security and Extensions. Each area has interactive tables (sort, filter, click a row to expand), and each finding links to the data behind it.

  • Free: every finding in the order to fix them, vital signs, every fix, remediation SQL and verification step, and all collected evidence and CSV export.
  • Workspace ($12 a month): retained history, PDF, a share link, scheduled uploads and alerts. Every finding, explanation, fix, available SQL recommendation and comparison with your previous available checkup is free.

Optional grants (more checks)

Two extra checks need a little more access. Both are optional and neither reads your table contents:

-- lets us check sequences (integer primary keys running out of numbers)
grant select on all sequences in schema public to checkup_reader;
-- measures real table bloat (cheap: uses the visibility map)
create extension if not exists pgstattuple;

Without them those checks are shown as skipped, with the reason, rather than guessed.

Connection tips

  • Use a direct connection or a session-mode pooler, not a transaction-mode pooler.
  • The database must be reachable from the internet. If access is restricted by IP address, the scan can't connect.
  • TLS: remote hosts require an encrypted connection with a verified certificate by default. There is no automatic fallback. For a provider with a private CA, add sslrootcert to the connection URL or set PGSSLROOTCERT when running locally.

When checks are skipped

If your role lacks a privilege or an extension is missing, that check is skipped and listed at the bottom of the report. The rest of the scan still runs.

PreviousOverviewNextChecks reference