pgFirstAid

curl -fsSL https://raw.githubusercontent.com/randoneering/pgFirstAid/main/pgFirstAid.sql | psql -d YOUR_DB

What is pgFirstAid?

A single SQL function and view that gives you a prioritized list of actions to improve your PostgreSQL database’s stability and performance.

Inspired by Brent Ozar’s FirstResponderKit for SQL Server, but built for Postgres, by people who run Postgres in production.

Features

• Zero Dependencies - Single SQL file, no external tools required
• Detailed Checks - Built-in health checks covering critical performance and stability issues
• Prioritized Results - Issues ranked by severity (CRITICAL → HIGH → MEDIUM → LOW → INFO)
• Actionable Recommendations - Each issue includes specific remediation steps
• Documentation Links - Direct links to official PostgreSQL documentation for deeper learning
• Optional pg_stat_statements Checks - Runs additional query workload checks when that extension is installed

Install

curl -fsSL https://raw.githubusercontent.com/randoneering/pgFirstAid/main/pgFirstAid.sql | psql -d YOUR_DB

Then run it (the function is the primary interface; a view is also available):

--- functionSELECT * FROM pg_firstAid();--- viewSELECT * FROM v_pgfirstAid;

Filter by Severity

-- Show only critical issuesSELECT * FROM pg_firstAid() WHERE severity = 'CRITICAL';SELECT * FROM v_pgfirstAid WHERE severity = 'MEDIUM';-- Show critical and high priority issuesSELECT * FROM pg_firstAid() WHERE severity IN ('CRITICAL', 'HIGH');SELECT * FROM v_pgfirstAid WHERE severity IN ('CRITICAL', 'HIGH');

Filter by Category

Categories: Table Health, Query Health, Replication Health, System Health, Database Health

-- Check table healthSELECT * FROM v_pgfirstAid WHERE category = 'Table Health';

Count Issues by Severity

SELECT severity, COUNT(*) as issue_countFROM pg_firstAid()GROUP BY severityORDER BY MIN(CASE severity WHEN 'CRITICAL' THEN 1 WHEN 'HIGH' THEN 2 WHEN 'MEDIUM' THEN 3 WHEN 'LOW' THEN 4 ELSE 5 END);

Compatibility

• PostgreSQL 15–18 - Primary supported versions, active automated testing
• PostgreSQL 10+ - Supported
• PostgreSQL 9.x - Most features work (minor syntax adjustments may be needed)
• Managed databases: Amazon RDS, Amazon Aurora, Google Cloud SQL, Azure Database for PostgreSQL, and self-hosted PostgreSQL

Sponsors

pgFirstAid is supported by DigitalOcean, Neon, and the OSU Open Source Lab. Their sponsorship covers testing infrastructure and CI/CD pipelines that keep pgFirstAid reliable.

Inspired by

FirstResponderKit - Brent Ozar’s pioneering health-check suite for SQL Server.

Sponsors

pgFirstAid is supported by: