Managing Heroku Postgres Performance using the CLI (Internal Pilot)

Last updated February 21, 2025

This article is a work in progress, or documents a feature that is not yet released to all users. This article is unlisted. Only those with the link can access it.

Heroku Postgres Performance is currently in internal pilot. The products offered as part of the pilot aren’t intended for production use and are considered a Beta Service and are subject to the Beta Services terms at https://www.salesforce.com/company/legal/agreements.jsp.

The Heroku Data Performance CLI plugin for the Heroku CLI allows you to create, manage, scale, and destroy Postgres Performance databases. This article includes the help texts for each of the plugin’s commands. You can see help text in your terminal with $ heroku data --help.

The plugin provides these commands:

Install the Heroku CLI

You must install the Heroku CLI before adding the Heroku Data Performance CLI plugin. See Heroku CLI for instructions.

Install the Heroku Data Performance CLI Plugin

To install the plugin, run the CLI command:

$ heroku plugins install data-beta

heroku data:pg:create

Creates a Postgres Performance add-on

USAGE
  $ heroku data:pg:create TIER -a <value> [--level <value>] [--name <value>] [--as <value>] [--wait]
    [--high-availability] [--network private|shield] [--readers <value>]

ARGUMENTS
  TIER  Performance Postgres tier

FLAGS
  -a, --app=<value>             (required) app to run command against
      --as=<value>              name for the initial add-on attachment
      --[no-]high-availability  enable a high-availability cluster by provisioning a warm standby writer
      --level=<value>           set the compute scale
      --name=<value>            name for the add-on resource
      --network=<option>        set the networking for the add-on
                                <options: private|shield>
      --readers=<value>         provisions a specified number of follower instance pools
      --wait                    watch the add-on creation status and exit when complete

DESCRIPTION
  Creates a Postgres Performance add-on

EXAMPLES
  $ heroku data:pg:create performance --level 4G-Performance -a example-app

Example

$ heroku data:pg:create performance --level 4G-Performance -a example-app
? Select a level 4G-Performance
Creating a 4G-Performance database on ⬢ example-app... ⡿
Database should be available soon

heroku data:pg:info

Gets details on a Postgres Performance add-on

USAGE
  $ heroku data:pg:info ADDON [-a <value>]

ARGUMENTS
  ADDON  Name of the add-on, the attachment name, or related config var on an app

FLAGS
  -a, --app=<value>  app to run command against

DESCRIPTION
  Gets details on a Postgres Performance add-on

EXAMPLES
  $ heroku data:pg:info database_name

Example

$ heroku data:pg:info HEROKU_POSTGRESQL_COBALT
=== postgresql-rugged-24211 as HEROKU_POSTGRESQL_COBALT_URL on ⬢ example-app

Tier: performance
App: example-app
Version: 16.1
Status: Scaling
Created: 1/26/2025, 4:21:11 PM
Tables: 0 / 4000 (In compliance)
Data: 7.64 MB / 128 TB (0.0%) (In compliance)
=== Compute

=== writer (Available) 1 x 4G-Performance: HEROKU_POSTGRESQL_COBALT_URL

writer.0: up (~ 3d ago)

=== readers (Provisioning) 3 x 4G-Performance: HEROKU_POSTGRESQL_COBALT_READERS_URL

readers.0: up (~ 3h ago)
readers.1: up (~ 3h ago)
readers.2: creating (~ 1m ago)

heroku data:pg:scale

Creates, scales, and destroys instance pools on a Postgres Performance add-on

USAGE
  $ heroku data:pg:scale ADDON -a <value> [--count <value>] [--level <value>] [--pool <value>]
    [--high-availability] [--confirm <value>]

ARGUMENTS
  ADDON  Name of the add-on. If targeting an app, you can use an env var associated with the add-on.

FLAGS
  -a, --app=<value>             (required) app to run command against
      --confirm=<value>         confirm scale action
      --count=<value>           adjust the instance count of a pool
      --[no-]high-availability  enable a high-availability cluster by provisioning a warm standby writer
      --level=<value>           adjust compute scale
      --pool=<value>            adds a named instance pool if one doesn't exist, or scales the existing instance pool based on the level and instance flags

DESCRIPTION
  Creates, scales, and destroys instance pools on a Postgres Performance add-on

EXAMPLES
  $ heroku data:pg:scale database_name -a example-app

Example

$ heroku data:pg:scale HEROKU_POSTGRESQL_COBALT --pool=my-new-pool --level 4G-Performance --count 1 -a example-app

Updates applied to postgresql-rugged-24211:
 Factor    From To
 ───────── ──── ──────────────
 level     null 4G-Performance
 followers 0    1

heroku data:pg:destroy

Destroys a Postgres Performance add-on

USAGE
  $ heroku data:pg:destroy ADDON [-f] [-c <value>] [--wait] [-a <value>]

ARGUMENTS
  ADDON  Name of the add-on, the attachment name, or related config var on an app

FLAGS
  -a, --app=<value>      app to run command against
  -c, --confirm=<value>  skip confirmation prompts by passing in the app name
  -f, --force            allow destruction even if connected to other apps
      --wait             watch database destruction status and exit when complete

DESCRIPTION
Destroys a Postgres Performance add-on

EXAMPLES
  $ heroku data:pg:destroy database_name

Example

$ heroku data:pg:destroy HEROKU_POSTGRESQL_COBALT --confirm example-app

heroku data:pg:psql

Opens a psql shell to a Postgres Performance add-on

USAGE
  $ heroku data:pg:psql DATABASE -a <value> [-c <value>] [--credential <value>] [-f <value>] [-p <value>] [-r
    <value>]

ARGUMENTS
  DATABASE  Name of the add-on, the attachment name, or related config var on an app

FLAGS
  -a, --app=<value>         (required) app to run command against
  -c, --command=<value>     SQL command to run
  -f, --file=<value>        SQL file to run
  -p, --pool=<value>        reader instance pool to connect to (only Performance-tier databases)
  -r, --remote=<value>      git remote of app to use
      --credential=<value>  credential to use

DESCRIPTION
  opens a psql shell to a Postgres Performance add-on

EXAMPLES
  $ heroku data:pg:psql database_name -a example-app

Example

$ heroku data:pg:psql HEROKU_POSTGRESQL_COBALT -a example-app
--> Connecting to postgresql-rugged-24211
Pager usage is off.
psql (15.5, server 16.1)
WARNING: psql major version 15, server major version 16.
Some psql features might not work.
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

heroku data:pg:docs

Opens the Heroku Postgres Performance documentation in your web browser

USAGE
  $ heroku data:pg:docs [--browser <value>]

FLAGS
  --browser=<value>  browser to open docs with (example: "firefox", "safari")

DESCRIPTION
  Opens the Heroku Postgers Performance documentation in your web browser

EXAMPLES
  $ heroku data:pg:docs

Example

$ heroku data:pg:docs

Feedback

Log in to submit feedback.