Getting Started with Heroku Postgres Performance (Internal Pilot)
Last updated March 17, 2025
Table of Contents
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.
Heroku Postgres Performance is our new database offering on new and improved infrastructure. To learn more about what Performance databases provide and use cases, see the Performance Features and Components and Use Cases sections.
In this guide, we walk through creating, managing, and removing a Performance database.
Install the Heroku Data Performance CLI Plugin
The Heroku Data Performance CLI plugin lets you to set up and manage Performance Postgres databases. To install the plugin, run the CLI command:
$ heroku plugins:install data-beta
See Managing Heroku Postgres Performance using the CLI (Pilot) for the CLI command reference.
Provisioning a Database
See Heroku Postgres Performance Plan Levels for Performance plan level details.
To provision a database with the default options, run the data:pg:create command and select the database level:
$ heroku data:pg:create performance -a example-app
? Select a level (Use arrow keys)
❯ 4G-Performance
8G-Performance
16G-Performance
32G-Performance
64G-Performance
128G-Performance
256G-Performance
384G-Performance
512G-Performance
768G-Performance
1024G-Performance
You can also provision a database with customizable options. To create a 4G-Performance database in a Private Space with one follower pool with two instances and high availability enabled, run the command:
$ heroku data:pg:create performance --level 4G-Performance --readers=2 --high-availability --network private -a example-app
Your database can take up to 30 minutes to become available.
After provisioning, you can see the details about the database with data:pg:info:
$ 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: 9/26/2024, 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)
Enable and Disable High Availability
See High Availability for how high availability works in Performance databases.
You can enable HA with the --high-availability flag when you provision a database. You can also enable HA with the data:pg:scale command:
$ heroku data:pg:scale HEROKU_POSTGRESQL_ORANGE --high-availability
Updates applied to postgresql-flexible-44916:
Factor From To
───────────────── ──────── ───────
high availability disabled enabled
Your postgres resource scaling should be complete shortly, use data:pg:info postgresql-flexible-44916 to track
To disable HA, run the command:
$ heroku data:pg:scale HEROKU_POSTGRESQL_ORANGE --no-high-availability
Updates applied to postgresql-flexible-44916:
Factor From To
───────────────── ──────── ───────
high availability enabled disabled
Your postgres resource scaling should be complete shortly, use data:pg:info postgresql-flexible-44916 to track
Scale Instance Pools
See Instance Pools for more information on instance pools in Performance databases.
Add a Pool
This command creates a follower pool named my-new-pool with one 4G-Performance compute instance:
$ heroku data:pg:scale HEROKU_PHEROKU_POSTGRESQL_YELLOW --pool=my-new-pool --level 4G-Performance --count 1 --app example-app
Updates applied to postgresql-acute-35199:
Factor From To
───────── ──── ──────────────
level null 4G-Performance
followers 0 1
Scale an Existing Pool
This command scales the existing leader instance in the leader pool from 4G-Performance to 8G-Performance:
$ heroku data:pg:scale HEROKU_POSTGRESQL_YELLOW --level 8G-Performance --app example-app
Updates applied to postgresql-acute-35199:
Factor From To
───────── ────────────── ──────────────
level 4G-Performance 8G-Performance
This command scales the existing instance level in a follower pool from 4G-Performance to 8G-Performance, and increases the follower instance count:
$ heroku data:pg:scale HEROKU_POSTGRESQL_EKOZIL_URL --pool=my-pool --level 8G-Performance --count 2 --app example-app
Updates applied to postgresql-acute-35199:
Factor From To
───────── ────────────── ──────────────
level 4G-Performance 8G-Performance
followers 1 2
Destroy a Pool
This command scales down the number of instances in a follower pool to zero, which destroys the pool:
Scaling down follower instances to zero also removes the config var of the follower pool.
heroku data:pg:scale HEROKU_POSTGRESQL_YELLOW --count 0 --app example-app
Updates applied to postgresql-acute-35199:
Factor From To
───────── ────────────── ──
level 4G-Performance
followers 3 0
Connect with psql
You must have PostgreSQL installed on your system to use heroku data:pg:psql.
You can establish a psql session with your database to execute queries and issue commands:
$ heroku data:pg:psql HEROKU_POSTGRESQL_YELLOW --app example-app
--> Connecting to postgresql-acute-35199
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.
Remove the Database
To destroy your Performance database, run the command:
$ heroku data:pg:destroy <DB name> --confirm example-app
Next Steps
Stay up to date on new features added to the pilot by checking the Pilot Changelog section. Be on the lookout for product feedback surveys and share how you’re using Performance databases and what features you’d like to see supported.