GitHub and CI

Run a checkup on a schedule, see the findings under the run, and fail a build when something regresses. The connection string stays in your repository's secrets. Nothing is uploaded unless you add a token.

The quick way: fork and go

pgcheckup/checkup-template is a repository with the weekly workflow already in it. Use it as a template, add one secret, DATABASE_URL, and run the workflow once. The report appears under the run in the Actions tab, and each week's run is compared with the one before.

In your own repository

- uses: pgcheckup/checkup-action@v1
  with:
    database-url: ${{ secrets.DATABASE_URL }}
    fail-on: warning   # optional

Or write the whole workflow yourself:

npx pg-checkup schedule --summary --write

Both put the findings in the run summary and compare with the previous run. The previous file is kept in the Actions cache, which GitHub clears after 7 days without use, so a weekly schedule keeps it and a monthly one starts fresh.

With Workspace: history, comparison and alerts on the site

In your repository:

npx pg-checkup schedule --write

This writes .github/workflows/pg-checkup.yml. It runs weekly (add --every daily for daily) and never overwrites an existing file. Upload tokens are part of Workspace, so a schedule needs an active plan. Add two repository secrets:

• DATABASE_URL: a statistics-only login. pg-checkup role prints the SQL that creates one.
• PGCHECKUP_TOKEN: create it in Settings (Workspace). It can add reports to your account and nothing else.

Commit the file and run it once from the Actions tab. Each upload is compared with the previous checkup of the same database, so the report shows what was fixed, what is new, and what is getting worse.

GitHub-hosted runners use changing IP addresses. If your database only accepts listed addresses, use a self-hosted runner inside your network.

Schedule it with cron

npx pg-checkup schedule --cron

prints one crontab line. The machine needs to reach the database, and DATABASE_URL and PGCHECKUP_TOKEN set in its environment.

Alerts

With an upload token, an upload that finds a new warning or critical finding, a finding that got more severe, or something that runs out within 30 days sends one email listing only those changes. A schedule that stops arriving also sends one email. Turn alerts off in Settings, Billing.

Fail a build

npx pg-checkup --fail-on warning --no-input --no-pace -o checkup.json

Exit codes: 0 completed, 1 a finding at or above --fail-on, 2 usage or runtime error, 3 the login has more access than a checkup needs, 4 the two files being compared are not the same database. Add --strict to exit 1 when any diagnostic view could not be read.

Compare two runs

npx pg-checkup compare before.json after.json

lists what was fixed, what is new, what is still open, and the numbers that changed. It exits 1 when something regressed and 4 when the two files are not the same database. When the statistics were reset between the two runs, it says so and states that counters such as calls and dead rows are not comparable.