Documentation

Get started with pgClaw

Install, connect, and diagnose your PostgreSQL databases in under 5 seconds. No database modifications required.

Quick Start

1. Install pgClaw

bash
pip install pgclaw

2. Connect to your database

bash
# Interactive setup
pgclaw setup

# Or specify connection details directly
pgclaw setup --host db.example.com --port 5432 --user postgres --dbname mydb

pgClaw stores connection details securely in your OS keychain. Passwords are never stored in plaintext config files.

3. Run your first health check

bash
pgclaw health-check --profile prod

4. Start continuous monitoring

bash
# Run as a background daemon
pgclaw monitor --profile prod --interval 30 --daemon &

# Or run interactively in the foreground
pgclaw monitor --profile prod --interval 30

Delivery Modes

CLI Tool

Run diagnostics from the command line

bash
pgclaw health-check --profile prod

Python Library

Coming Q3 2026. For now use the CLI or integrate via subprocess.

python
import subprocess
result = subprocess.run(
    ["pgclaw", "health-check", "--profile", "prod", "--output", "json"],
    capture_output=True, text=True
)
findings = json.loads(result.stdout)

Background Daemon

Run continuous monitoring in the background

bash
pgclaw monitor --profile prod --interval 30 --daemon &

Prometheus Metrics

Expose pgClaw metrics for your existing monitoring

bash
pgclaw exporter --port 9187 --profile prod --interval 30

Output Formats

pgClaw supports 6 output formats. Use --output to switch between them.

bash
# Terminal output (default) - colored, human-readable
pgclaw health-check --profile prod --output terminal

# JSON - for scripts and integrations
pgclaw health-check --profile prod --output json

# Markdown - for documentation and wikis
pgclaw health-check --profile prod --output markdown

# HTML - full report with styling, save and email
pgclaw health-check --profile prod --output html --save
pgclaw health-check --profile prod --output html --save --email team@company.com

# PDF - printable reports
pgclaw health-check --profile prod --output pdf --save

# Slack - formatted for Slack channels
pgclaw health-check --profile prod --output slack

Reports and History

Save reports for later

bash
# Save an HTML report
pgclaw health-check --profile prod --output html --save

# Save and email to your team
pgclaw health-check --profile prod --output html --save --email team@company.com

Browse and compare reports

bash
# List all saved reports
pgclaw reports list

# Compare two reports to see what changed
pgclaw reports compare report1.json report2.json

Interactive review

bash
# Review findings one-by-one, provide feedback
pgclaw health-check --profile prod --review

Interactive review walks through each finding and lets you approve, dismiss, or provide feedback. Your feedback trains pgClaw to suppress noise over time.

Finding suppression

bash
# List suppressed findings
pgclaw suppressions list

# Remove a suppression by ID
pgclaw suppressions remove ID

Reject the same finding 3 times with the same reason and pgClaw auto-suppresses it. Your team knowledge becomes pgClaw's knowledge.

Autonomy Levels

pgClaw operates at 5 autonomy levels. You control how much authority the agent has - from observe-only to full autonomous remediation.

L1

Observe

Collect telemetry and report findings. No actions taken. Default for new installations.

L2

Recommend

Everything in Level 1, plus generate remediation plans with risk scores. Still no actions taken.

L3

Approve

Everything in Level 2, plus execute approved remediations. Requires explicit DBA approval via Jira, Slack, or email before each action.

L4

Auto-Safe

Automatically execute low-risk remediations (VACUUM, ANALYZE, kill idle sessions). Medium and high-risk actions still require approval.

L5

Autonomous

Full autonomous operation. All remediations execute automatically. Destructive operations (DROP, REINDEX CONCURRENTLY on large tables) ALWAYS require human approval regardless of level.

Change Management

When pgClaw recommends a remediation at autonomy Level 3+, it creates a ticket in Jira or sends a Slack message and waits for DBA approval. The approval workflow supports three responses:

APPROVED PROCEED

Execute the remediation immediately.

APPROVED 3/30 4am EST

Schedule execution for a specific maintenance window. pgClaw holds the action until the specified time.

REJECTED

Decline the remediation. pgClaw asks for a reason and stores it for future reference. Repeated rejections auto-suppress the finding.

Every action - approved, scheduled, or rejected - is logged in the encrypted audit trail with timestamp, initiator, and result.

Integrations

Patroni cluster status

bash
pgclaw patroni status --profile prod

Backup verification

bash
pgclaw backup status --profile prod

Slack bot (interactive)

bash
# Start the Slack bot with action buttons
pgclaw slack-bot start

The Slack bot posts findings with interactive action buttons. DBAs can approve, reject, or schedule remediations directly from Slack.

Email reports

bash
# Send report to your team via email
pgclaw health-check --profile prod --output html --save --email team@company.com

Multi-Cluster Configuration

pgClaw supports managing multiple clusters from a single configuration file at ~/.pgclaw/config.yaml.

yaml
connections:
  prod:
    host: db-prod-1.example.com
    port: 5432
    dbname: myapp
    user: pgclaw_monitor
    sslmode: require

  staging:
    host: db-staging.example.com
    port: 5432
    dbname: myapp_staging
    user: pgclaw_monitor
    sslmode: require

Passwords are resolved through the secrets hierarchy: environment variables (PGCLAW_PROD_PRIMARY_PASSWORD), OS keychain, or .pgpass. Never store passwords in config files - pgClaw will raise a SecurityError.

Connect to Sage

pgClaw works standalone with 93 diagnostic rules. Connect to Sage for AI-powered correlation analysis, anomaly detection, and collective learning from your DBA team decisions. Available on Pro tier and above.

yaml
# Add to ~/.pgclaw/config.yaml
sage:
  api_url: https://api.dbabrain.ai
bash
# Set your Sage API key
export PGCLAW_SAGE_API_KEY='your-api-key'

# Run health check - automatically uses Sage when configured
pgclaw health-check --profile prod

Security Note

Credentials never leave your infrastructure. pgClaw sends only normalized numeric telemetry to Sage - no query text, no table names, no schema details.

Security

Credential Handling

Passwords resolved via environment variables or OS keychain. Never stored in plaintext. Config files scanned for secrets on load.

Network Security

SSL/TLS required by default (sslmode=require). All Sage API connections enforced HTTPS. SSH host key verification enabled.

SQL Injection Prevention

All queries in auditable .sql files. Parameterized queries via psycopg.sql.SQL. Table/index names validated against strict regex.

Audit Trail

Every action logged with timestamp, action, target, initiator, and result. Append-only, encrypted with SQLCipher when available.

File Permissions

Sensitive files written with 0600 (owner read/write only). Config, audit DB, and feedback DB all protected.

Frequently Asked Questions

Ready to get started?

Install pgClaw and run your first health check in under 5 seconds.

Create Free AccountBack to Home