feat: exclude long-running physical backup queries from pg:ps results

[iriberri]

Summary

Heroku Postgres runs physical backups as part of continuous protection. These can take some time and the underlying pg_start_backup (on PG15+) queries will appear as long running, idle in transaction processes.

These are unnecessary noise and can confuse users over processes they have no control over. The backup process queries will of course be still visible through pg_stat_activity, but we should remove it from our troubleshooting commands to reduce confusion - it is expected for these long transactions to exist on the database during base backups.

See: https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADMIN-BACKUP and https://www.postgresql.org/docs/current/continuous-archiving.html.

Related: heroku/heroku-pg-extras#285

Type of Change

Breaking Changes (major semver update)

• Add a ! after your change type to denote a change that breaks current behavior

Feature Additions (minor semver update)

• feat: Introduces a new feature to the codebase

Patch Updates (patch semver update)

• fix: Bug fix
• deps: Dependency upgrade
• revert: Revert a previous commit
• chore: Change that does not affect production code
• refactor: Refactoring existing code without changing behavior
• test: Add/update/remove tests

Testing

Notes:

This is a minor change and its impact is only visible, in normal conditions, when running the command against a database with a long running command. It is therefore not immediately testable by non-data operators that can't start a backup on the database that this change aims to exclude from the results.

Steps:

1. Passing CI suffices, overall

but:

1. On a database with a long-running base backup, run pg:ps. The result should not include the internal superuser (postgres) connection waiting idle in transaction for pg_backup_start.

Screenshots (if applicable)

Current main - the "idle in transaction" process is listed:

   pid   |        state        |                 source                 |       username       |   running_for   |       transaction_start       | waiting |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             query
---------+---------------------+----------------------------------------+----------------------+-----------------+-------------------------------+---------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
....
 2969256 | active              |                                        |                      | 01:33:10.960384 | 2026-04-17 12:32:12.329183+00 | t       | autovacuum: VACUUM pg_toast.pg_toast_953633339
 2818310 | idle in transaction |                                        | postgres             | 08:46:55.147216 | 2026-04-17 05:18:28.142351+00 | t       | SELECT file_name,   lpad(file_offset::text, 8, '0') AS file_offset FROM pg_walfile_name_offset(  pg_backup_start('freeze_start_2026-04-17T05:18:28.142280+00:00'))
  327427 | active              | standby                                | postgres             |                 |                               | t       | START_REPLICATION 1F4C43/1D000000 TIMELINE 11
  295818 | active              | follower                               | postgres             |                 |                               | t       | START_REPLICATION 1F4C23/E000000 TIMELINE 11

Running the command on my branch after that - the process is no longer listed, as expected:

   pid   | state  |                 source                 |       username       |   running_for   |       transaction_start       | waiting |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              query
---------+--------+----------------------------------------+----------------------+-----------------+-------------------------------+---------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
...
 2969256 | active |                                        |                      | 01:36:56.262495 | 2026-04-17 12:32:12.329183+00 | f       | autovacuum: VACUUM pg_toast.pg_toast_953633339
  327427 | active | standby                                | postgres             |                 |                               | t       | START_REPLICATION 1F4C43/1D000000 TIMELINE 11
  295818 | active | follower                               | postgres             |                 |                               | t       | START_REPLICATION 1F4C23/E000000 TIMELINE 11

Back to main for sanity check, the previously filtered process reappears:

   pid   |        state        |                 source                 |       username       |   running_for   |       transaction_start       | waiting |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              query
---------+---------------------+----------------------------------------+----------------------+-----------------+-------------------------------+---------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

...
 2969256 | active              |                                        |                      | 01:37:31.864287 | 2026-04-17 12:32:12.329183+00 | f       | autovacuum: VACUUM pg_toast.pg_toast_953633339
 2818310 | idle in transaction |                                        | postgres             | 08:51:16.051119 | 2026-04-17 05:18:28.142351+00 | t       | SELECT file_name,   lpad(file_offset::text, 8, '0') AS file_offset FROM pg_walfile_name_offset(  pg_backup_start('freeze_start_2026-04-17T05:18:28.142280+00:00'))
  327427 | active              | standby                                | postgres             |                 |                               | f       | START_REPLICATION 1F4C43/1D000000 TIMELINE 11
  295818 | active              | follower                               | postgres             |                 |                               | t       | START_REPLICATION 1F4C23/E000000 TIMELINE 11

Related Issues

GUS work item: W-22101694

[iriberri]

Closing - we'll want to stick to heroku/heroku-pg-extras#285. pg:ps ultimately reports running queries on the database and filtering this process would be exposing incomplete information. We'll work on related but different improvements for this commonly confusing topic.