refactor: use @heroku/sdk for pg:backups commands (part 3)

[erika-wallace]

Summary

Continues the @heroku/sdk migration for pg:backups commands. This PR moves pg:backups:capture and pg:backups:restore off raw this.heroku.* calls and the legacy backupsFactory polling helper, onto the SDK's data.backup.captureAndWait and data.restore.restoreAndWait extensions. Bumps @heroku/sdk to ^0.9.0.

Changes Made

• pg:backups:capture now resolves the database via data.database.describe and performs the capture + wait-for-completion in a single data.backup.captureAndWait call.
• pg:backups:restore now looks up existing backups via data.transfer.listByApp and performs the restore + wait-for-completion in a single data.restore.restoreAndWait call.
• Added two shared helpers to src/lib/pg/backups.ts:
  • constructWaitOptions(interval, verbose, action) builds the intervalMs/onPoll/waitPoller options consumed by both captureAndWait and restoreAndWait.
  • reportTransferFailure(error, transferType) formats the "did not finish" error message from a TransferFailedError, replacing the equivalent inline catch block in the old wait() method.

Behavior notes (also documented in V12-CHANGES.md)

• pg:backups:capture now names the DATABASE argument, or DATABASE_URL when that argument is omitted, in the "not yet provisioned" error instead of the add-on resource name.

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:

Requires an app with a Heroku Postgres legacy-tier database attached.

Setup:

1. Pull down this branch
2. npm i && npm run build
3. heroku logout && HEROKU_NETRC_WRITE=true ./bin/run login

Steps

1. Create a backup. Verify the backup starts, shows progress, and completes successfully.

./bin/run pg:backups:capture <database> --app <app>

2. Create a backup with verbose logs. Verify same output as above with log lines.

./bin/run pg:backups:capture <database> --app <app> --verbose

3. List backups. Verify the two new backups are listed.

./bin/run pg:backups --app <app>

4. Restore a backup (with extensions). Verify the restore starts, shows progress, and completes successfully.

./bin/run pg:backups:restore <backup-id> <database> --app <app> --confirm <app> --extensions uuid-ossp

5. List restores. Verify the two new restores are listed.

./bin/run pg:backups --app <app>

Cleanup

• ./bin/run logout

Screenshots (if applicable)

Related Issues

GUS work item: W-23386457

[michaelmalave]

Solid part-3 of the @heroku/sdk migration — the capture/restore wiring, the shared wait/failure helpers, and the nock-to-SDK-stub test rewrite all read well, and I confirmed the happy paths live against a real app (capture, verbose capture, and list all work on 0.9.0). One thing to fix before merge, though: I verified against 0.9.0 that a mistyped/unknown DATABASE argument now reports "not yet provisioned / run addons:wait" instead of the old "Unknown database: X. Valid options are: ..." — a confirmed before/after regression on the error path (detail inline). The PR is labeled refactor (no behavior change), so the capture error-path change is worth a look against that intent.

[michaelmalave]

Tests complete successfully, this looks good! Just one thing to review and fix.