---

name: heroku-postgres description: Operate Heroku Postgres with a safe inspection-first workflow. Use when the agent needs to provision, inspect, attach, promote, back up, restore, diagnose, or reason about credentials and data movement for Heroku Postgres.

Heroku Postgres

Manage Heroku Postgres by separating inspection from destructive database changes.

Start with a database snapshot

Resolve this installed skill's directory first. Do not assume the current workspace contains the skill source repository.

Run the bundled helper from this skill's scripts/ directory:

python3 /path/to/heroku-postgres/scripts/postgres_snapshot.py --app <app>

If no app is known yet, run it without --app to inspect CLI and auth readiness only.

Read-only-first flow

Begin with:

• heroku pg:info -a <app>
• heroku pg:backups -a <app>
• heroku pg:credentials -a <app>
• heroku pg:psql -a <app> only when the user explicitly wants direct SQL inspection
• heroku pg:diagnose -a <app> when available and appropriate

Use the inspection results to identify the attached database, the current role of each attachment, and the backup posture before proposing a change.

Change operations

Ask for confirmation before:

• provisioning a new database
• promoting a follower or attachment
• restoring a backup
• rotating credentials
• unlinking or destroying a database
• running pg:push or pg:reset

When moving data, explain source, destination, downtime risk, and rollback posture first.

Secret handling

• Do not print database URLs unless the user explicitly asks for them.
• Prefer credential rotation workflows over sharing long-lived credentials.
• Summarize attachment names and roles without exposing secrets.

References

• Read references/postgres-ops.md for command catalogs, safety gates, and source links.