Last updated July 17, 2026

Heroku Postgres is integrated directly into the Heroku CLI and offers many helpful commands that simplify common database tasks.

Postgres-Related CLI Commands

There are different commands depending on the database tier. Use the data:pg:* commands on Advanced databases (Limited GA). Use the pg:* commands on Essential and classic Postgres databases.

Postgres-Related CLI Plugins

• Heroku mTLS Plugin CLI Commands
• Heroku CLI Data Plugin for Heroku Streaming Data Connectors and Getting Started with Heroku Data Labs

data:pg:info and pg:info

To see all Heroku Postgres databases provisioned on your app and the identifying characteristics of each, such as database size, status, number of tables, and PG version, use heroku data:pg:info for Advanced databases (Limited GA) and heroku pg:info for non-Advanced databases:

$ heroku pg:info -a example-app
=== DATABASE_URL, HEROKU_POSTGRESQL_RED

Plan:                  Standard 0
Status:                Available
Data Size:             320 MB / 64 GB (0.50%)
Tables:                39
PG Version:            16.9
Connections:           13/200
Connection Pooling:    Available
Credentials:           8
Fork/Follow:           Available
Rollback:              earliest from 2026-03-22 12:55 UTC
Created:               2024-08-26 09:52
Region:                eu
Data Encryption:       In Use
Continuous Protection: On
Enhanced Certificates: Off
Upgradable Extensions: Yes
Maintenance:           not required
Maintenance window:    Sundays 14:30 to 18:30 UTC
Add-on:                postgresql-octagonal-85179

=== HEROKU_POSTGRESQL_GRAY
Plan         Standard 2
Status       Available
Data Size    82.8 GB / 256 GB (32.34%)

data:pg:psql and pg:psql

To establish a psql session with your Heroku Postgres database, use heroku data:pg:psql for Advanced databases (Limited GA) and heroku pg:psql for non-Advanced databases:

$ heroku pg:psql -a example-app
--> Connecting to postgresql-octagonal-85179
psql (17.2 (Postgres.app), server 16.9 (Ubuntu 16.9-1.pgdg20.04+1))
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: none)
Type "help" for help.

example-app::DATABASE=>

The command uses the database located at DATABASE_URL by default. If you have more than one database, specify the database you want to connect to as the first argument to the command. You can use the database’s add-on name or its attachment name:

$ heroku pg:psql postgresql-clean-71224 -a example-app
--> Connecting to postgresql-clean-71224
...

pg:push and pg:pull

pg:pull

The heroku:pg:pull command pulls remote data from a Heroku Postgres database to a database on your local machine. This command creates a new local database named mylocaldb and then pulls data from the database at DATABASE_URL from the app example-app:

$ heroku pg:pull DATABASE_URL mylocaldb --app example-app

You can also specify the name of the database add-on to pull data from:

$ heroku pg:pull postgresql-animate-91581 mylocaldb --app example-app

To prevent accidental data overwrites and loss, the local database must not exist. Heroku prompts you to drop an existing local database before proceeding.

If providing a Postgres user or password for your local DB is necessary, use the appropriate environment variables. For example:

$ PGUSER=postgres PGPASSWORD=password heroku pg:push mylocaldb DATABASE_URL --app example-app

pg:push

The heroku pg:push command pushes data from a local database into a remote Heroku Postgres database. This command takes the local database mylocaldb and pushes it to the database at DATABASE_URL on the app example-app:

$ heroku pg:push mylocaldb DATABASE_URL --app example-app

You can also specify the name of the database add-on to push data to:

$ heroku pg:push postgresql-animate-91581 mylocaldb --app example-app

To prevent accidental data overwrites and loss, the remote database must be empty. Heroku prompts you to pg:reset a remote database that isn’t empty.

Usage of the PGUSER and PGPASSWORD for your local database is also supported for pg:push, just like for the pg:pull command. For example:

$ PGUSER=postgres PGPASSWORD=password heroku pg:push mylocaldb DATABASE_URL --app example-app

pg:ps, pg:kill, pg:killall

These commands give you view and control over currently running queries.

The pg:ps command queries the pg_stat_activity view in Postgres to give a concise view into currently running queries.

$ heroku pg:ps -a example-app
   pid   | state  |      source      | username |   running_for   |       transaction_start       | waiting |           query
---------+--------+------------------+----------+-----------------+-------------------------------+---------+---------------------------
 1330767 | active | psql interactive | u3a8a    | 00:00:13.251843 | 2026-06-29 15:49:30.818408+00 | t       | select * from hello;
 1330766 | active | psql interactive | u3a8a    | 00:00:19.454818 | 2026-06-29 15:49:24.615433+00 | t       | select * from observations …
(2 rows)

You can then use the heroku pg:kill command to cancel a query or terminate a process by specifying the process pid. Without any arguments, the command uses the pg_cancel_backend function to cancel the query that the process is running. With the--force option, the command uses the pg_terminate_backend function to drop the entire connection for that query.

$ heroku pg:kill 1330767 -a example-app
 pg_cancel_backend
-------------------
 t
(1 row)

$ heroku pg:kill --force 1330766 -a example-app
 pg_terminate_backend
----------------------
 t
(1 row)

The heroku pg:killall command uses the pg_terminate_backend function to terminate every connection on your database.

$ heroku pg:killall -a example-app
Terminating connections for all credentials... done

pg:promote

Promote a database to be the primary for your app with the heroku pg:promote command.

pg:promote updates the value of the DATABASE_URL config var with the newly promoted database’s connection string. It also creates an alternate attachment for the old primary database, assigned with a new HEROKU_POSTGRESQL_<color>_URL config var. The promotion process triggers a release and restarts the app.

$ heroku pg:promote HEROKU_POSTGRESQL_GRAY_URL -a example-app
Ensuring an alternate alias for existing DATABASE_URL... HEROKU_POSTGRESQL_PINK_URL
Promoting HEROKU_POSTGRESQL_GRAY_URL to DATABASE_URL... done

Promotions When Using Connection Pooling

If your old primary used Connection Pooling attached with the default name DATABASE_CONNECTION_POOL, pg:promote reattaches the connection pooler to the new primary.

If you use Connection Pooling attachments under non-default names, you must update them after running pg:promote. Activate Connection Pooling on your new primary to repoint the connection pooling URL:

$ heroku pg:connection-pooling:attach DATABASE_URL --as MY_DATABASE_CONNECTION_POOL -a example-app
Enabling Connection Pooling on postgresql-octagonal-85179 to example-app... done
Setting MY_DATABASE_CONNECTION_POOL config vars and restarting example-app... done, v853

pg:reset

The PostgreSQL user your database is assigned doesn’t have permission to create or drop databases. To delete all the content in your database use the heroku pg:reset command.

$ heroku pg:reset DATABASE -a example-app
 ›   Warning: Destructive action
 ›   postgresql-fitted-17726 will lose all of its data
 ›

To proceed, type example-app or re-run this command with --confirm example-app: example-app
Resetting postgresql-fitted-17726... done