pgdoctor

A command-line tool and Go library for running health checks against PostgreSQL databases.

go install github.com/fresha/pgdoctor/cmd/pgdoctor@latest

View on GitHub Browse Checks

-- checks

-- categories

100% read-only

Read-only & Production Safe

Queries only system catalogs. No data modified, ever.

Built-in Checks

Configs, indexes, vacuum, schema, and performance.

CLI + Go Library

Use standalone or embed in your own Go tools.

JSON Output

Machine-readable output for CI/CD pipelines.

Quick Start

Get your PostgreSQL health report in seconds.

Run all checks

$ pgdoctor run "postgres://user:pass@localhost:5432/mydb"

# Or use an environment variable
$ export PGDOCTOR_DSN="postgres://..."
$ pgdoctor run

Filter checks

# Run only specific checks or categories
$ pgdoctor run --only connection-health,indexes

# Skip certain checks
$ pgdoctor run --ignore index-bloat,vacuum

Explore checks

# List all available checks
$ pgdoctor list

# Read detailed docs for a check
$ pgdoctor explain index-bloat

Output options

# JSON output for CI/CD
$ pgdoctor run --output json

# Verbose details, hide passing
$ pgdoctor run --detail verbose --hide-passing

Checks Reference

Production-safe checks organized across categories. Click any check to expand its documentation.

All documentation below is available offline via pgdoctor explain <check-id>

Go Library

Embed pgdoctor checks directly in your Go applications.

Simple, composable API

Import as a Go module and run checks programmatically. Filter, extend with custom checks, and process results however you need.

pgdoctor.Run(ctx, conn, checks, cfg, only, ignored) Execute checks

pgdoctor.AllChecks() Built-in check set

pgdoctor.ValidateFilters(checks, filters) Validate filters

main.go

package main

import (
    "context"
    "fmt"

    "github.com/fresha/pgdoctor"
    "github.com/jackc/pgx/v5"
)

func main() {
    ctx := context.Background()
    conn, _ := pgx.Connect(ctx, "postgres://localhost:5432/mydb")
    defer conn.Close(ctx)

    reports, err := pgdoctor.Run(
        ctx, conn, pgdoctor.AllChecks(), nil, nil,
    )
    if err != nil {
        panic(err)
    }

    for _, report := range reports {
        fmt.Printf("[%s] %s\n", report.CheckID, report.Name)
    }
}