Getting Started with Heroku Postgres Advanced (Limited GA)

Introduction

Heroku Postgres Advanced is in limited general availability. To start creating and using Advanced databases, open a ticket with Heroku Support to request access. Subscribe to our changelog to stay informed of when Heroku Postgres Advanced is generally available.

Heroku Postgres Advanced offers flexible customization options to fit every database need for your app. To learn more about what Advanced databases provide and use cases, see the Heroku Postgres Advanced Features and Components and Use Cases sections.

In this guide, we walk through creating, managing, and removing an Advanced database using the Postgres Advanced CLI commands.

This getting started guide covers features on Heroku Postgres Advanced-tier databases, not classic Postgres databases. To migrate your existing database to the Advanced tier, see Migrating to Heroku Postgres Advanced.

Provision a Database

Your database can take up to 30 minutes to become available.

To provision a database, run the data:pg:create command and follow the interactive prompts:

Select Configure Leader Pool and select the plan level for your database cluster.

$ heroku data:pg:create -a example-app
Create a Heroku Postgres Advanced database
Press Ctrl+C to cancel

→ Configure Leader Pool
  Configure Follower Pool(s)

? Select a Leader Pool Level: (Use arrow keys)
❯ 4G-Performance    2 vCPU     4 GB MEM  starting at ~$0.208/hour ($150/month)
  8G-Performance    2 vCPU     8 GB MEM  starting at ~$0.417/hour ($300/month)
  16G-Performance   2 vCPU    16 GB MEM  starting at ~$0.694/hour ($500/month)
  32G-Performance   4 vCPU    32 GB MEM  starting at ~$1.250/hour ($900/month)
...

Enable or disable high availability on your leader instance pool.

The leader pool has high availability enabled and includes a standby instance for redundancy. If you disable high availability, you remove the standby and you won't have redundancy on your database.

? Do you want to keep the high availability standby instance? (Use arrow keys)
> Keep high availability (HA)
   Remove high availability -$0.208/hour ($150/month)
  ──────────────
  Go back

Review your configuration and select Confirm.

✓ Configure Leader Pool ~$0.417/hour ($300/month)
  4G-Performance 2 vCPU 4 GB MEM ~$0.208/hour ($150/month)
  Standby (High Availability) ~$0.208/hour ($150/month)

? Confirm provisioning? (Use arrow keys)
> Confirm
  Go back

Creating a 4G-Performance database on ⬢ example-app... done
Database should be available soon
postgresql-rectangular-12345 is being created in the background. The app will restart when complete...
Run heroku data:pg:info postgresql-rugged-24211 -a example-app to check creation progress.

Optionally, you can create follower instance pools for your database or exit the create command. You can also create them later in the Add a Follower Instance Pool section.

You can configure a follower pool while the leader pool is being configured. (Use arrow keys)
> Configure a follower pool
  Exit

? Select a Follower Pool Level: (Use arrow keys)
❯ 4G-Performance    2 vCPU     4 GB MEM  starting at ~$0.208/hour ($150/month)
  8G-Performance    2 vCPU     8 GB MEM  starting at ~$0.417/hour ($300/month)
  16G-Performance   2 vCPU    16 GB MEM  starting at ~$0.694/hour ($500/month)
  32G-Performance   4 vCPU    32 GB MEM  starting at ~$1.250/hour ($900/month)
...

Select the number of instances in your follower instance pool and give your instance pool a name.

A cluster can have up to 13 follower instances. Two or more instances in a pool enables high availability for redundancy.
Adding more instances distributes the load in the follower pool.

? Select the number of instances for this pool: (Use arrow keys)
   1 instance
   2 instances
❯ 3 instances
...

? Do you want to name this follower pool? (Use arrow keys)
> Yes
  No, assign a random name

? Enter a unique pool name (3-32 lowercase letters and numbers, no spaces):
follower-pool

Review your configuration and select Confirm.

✓ Configure Follower Pool ~$0.208/hour ($150/month)
  follower-pool
  4G-Advanced
  3 instances (High Availability)

> Confirm provisioning? (Use arrow keys)
> Confirm
  Go back

Configuring follower pool... done
Success: we're provisioning follower-pool follower pool on postgresql-rugged-24211.
Run heroku data:pg:info postgresql-rectangular-12345 -a example-app to check creation progress.

? Configure another follower pool? (y/N)

You can also provision a database with customizable options through the command flags.

View Your Database

After provisioning, you can see the details about the database with data:pg:info:

$ heroku data:pg:info HEROKU_POSTGRESQL_COBALT
=== ⛁ postgresql-rectangular-12345 on ⬢ example-app

Plan:       Advanced
Status:     Available
Data Size:  1.10 GB / 128.00 TB
Tables:     10 / 4000 (In compliance)
PG Version: 17.9
Rollback:   earliest from 2026-05-18 00:00 UTC
Region:     us
Created:    2026-05-18 00:00 UTC
Quotas:
  Storage:  1.10 GB (No quotas set)

=== Leader pool (attached as DATABASE)

✓ Available
Connections: 10 / 400 used
2 instances of 4G-Performance (HA):
leader.i3r507gt6dbscn: up
standby.i7fquhvs4efu74: up

=== Follower pool analytics (attached as DATABASE_ANALYTICS)

✓ Available
Connections: 50 / 800 used
3 instances of 4G-Performance (HA):
follower.ic7mb4lq0rkurk: up
follower.i7q78mp2fg4v15: up
follower.i751amp2mkl325: up

Attach Your Database Instance Pools

Attaching an instance pool creates a new config var with the pool’s connection string that your app can use to connect to your leader or follower instances. You can attach the leader instance pool and multiple follower instance pools on your database between multiple apps.

To attach the leader instance pool of your database to another app, run the command:

$ heroku data:pg:attachments:create postgresql-rectangular-12345 -a attached-app --as ATTACHED_DB
Attaching postgresql-rectangular-12345 to ⬢ attached-app... done
Setting ATTACHED_DB config vars and restarting ⬢ attached-app... done

To attach a follower instance pool on your database to another app, use the --pool flag and provide the name of the follower instance pool:

$ heroku data:pg:attachments:create postgresql-rectangular-12345 --pool=follower-pool -a attached-app --as FOLLOWER_DB
Attaching analytics-pool on postgresql-rectangular-12345 as FOLLOWER_DB to ⬢ attached-app... done
Setting FOLLOWER_DB config vars and restarting ⬢ attached-app... done

Update High Availability

See High Availability on Heroku Postgres for how high availability works in Advanced databases.

The leader instance pool includes a standby instance for high availability when you provision a database. You can update HA settings with the interactive data:pg:update command. Follow the prompts to select the leader instance pool on the database, and then select the option to to enable or disable high availability:

$ heroku data:pg:update -a example-app

? Select the Heroku Postgres Advanced database to update: (Use arrow keys)
   postgresql-horizontal-12345 (DATABASE)
> postgresql-rectangular-12345 (HEROKU_POSTGRESQL_COBALT)

Update postgresql-rectangular-12345 on ⬢ example-app
Press Ctrl+C to cancel

? Select the pool to update, or add a follower pool: (Use arrow keys)
> Leader: 4G-Performance 2 vCPU 4 GB MEM 2 instances starting at ~$0.208/hour ($150/month)
   Follower follower-pool: 4G-Performance 2 vCPU 4 GB MEM 3 instances starting at ~$0.208/hour ($150/month) each
  ──────────────
  Add a follower pool
  Exit

Update postgresql-rectangular-12345 on ⬢ example-app
Press Ctrl+C to cancel

? What do you want to do?: (Use arrow keys)
  Change pool level
❯ Remove high availability -$0.208/hour ($150/month)
  ──────────────
  Go back

Removing the high availability (HA) standby instance from postgresql-rectangular-12345... done

You can also remove HA during the interactive provisioning prompts, or use the --no-high-availability flag if you provision through flags.

Add a Follower Instance Pool

See Managing Instance Pools on Heroku Postgres Performance for more information on instance pools in Advanced databases.

You can create follower instance pools when you provision a database or create them for an existing database with the interactive data:pg:update command:

$ heroku data:pg:update -a example-app

? Select the Heroku Postgres Advanced database to update: (Use arrow keys)
   postgresql-horizontal-12345 (DATABASE)
❯ postgresql-rectangular-12345 (HEROKU_POSTGRESQL_COBALT)

Update postgresql-rectangular-12345 on ⬢ example-app
Press Ctrl+C to cancel

? Select the pool to update, or add a follower pool: (Use arrow keys)
  Leader: 4G-Performance 2 vCPU 4 GB MEM 2 instances starting at ~$0.208/hour ($150/month) each
  Follower follower-pool: 4G-Performance 2 vCPU 4 GB MEM 3 instances starting at ~$0.208/hour ($150/month) each
  ──────────────
❯ Add a follower pool
  Exit

Scale a Follower Instance Pool

See Managing Instance Pools on Heroku Postgres Performance for more information on instance pools in Advanced databases.

You can scale follower instance pools by either changing the instance level or changing the number of instances in the instance pool with the interactive data:pg:update command:

$ heroku data:pg:update -a example-app

? Select the Heroku Postgres Advanced database to update: (Use arrow keys)
  postgresql-horizontal-12345 (DATABASE)
❯ postgresql-rectangular-12345 (HEROKU_POSTGRESQL_COBALT)
  ──────────────
  Exit

Update postgresql-rectangular-12345 on ⬢ example-app
Press Ctrl+C to cancel

? Select the pool to update, or add a follower pool: (Use arrow keys)
  Leader: 4G-Performance 2 vCPU 4 GB MEM 2 instances starting at ~$0.208/hour ($150/month) each
❯ Follower follower-pool: 4G-Performance 2 vCPU 4 GB MEM 3 instances starting at ~$0.208/hour ($150/month) each
  ──────────────
  Add a follower pool
  Exit

Update postgresql-rectangular-12345 on ⬢ example-app
Press Ctrl+C to cancel

? Select the pool to update, or add a follower pool: (Use arrow keys)
  Leader: 4G-Performance 2 vCPU 4 GB MEM 2 instances starting at ~$0.208/hour ($150/month)
> Follower analytics: 16G-Performance 4 vCPU 16 GB MEM 1 instance starting ~$0.694/hour ($500/month)

? What do you want to do?: (Use arrow keys)
> Change pool level
  Update number of instances
  Destroy pool
  ──────────────
  Go back

? Select a Follower Pool Level: (Use arrow keys)
  -4G-Performance    2 vCPU     4 GB MEM  starting at ~$0.208/hour ($150/month) (current level)
❯8G-Performance    2 vCPU     8 GB MEM  starting at ~$0.417/hour ($300/month)
  16G-Performance   2 vCPU    16 GB MEM  starting at ~$0.694/hour ($500/month)  32G-Performance   4 vCPU    32 GB MEM  starting at ~$1.250/hour ($900/month)
  ...
  ──────────────
  Go back

Destroy a Follower Instance Pool

See Managing Instance Pools on Heroku Postgres Performance for more information on instance pools in Advanced databases.

Scaling down follower instances to zero doesn’t destroy the follower instance pool.

You can destroy a follower instance pool with the interactive data:pg:update command:

$ heroku data:pg:update -a example-app

? Select the Heroku Postgres Advanced database to update: (Use arrow keys)
  postgresql-horizontal-12345 (DATABASE)
❯ postgresql-rectangular-12345 (HEROKU_POSTGRESQL_COBALT)

Update postgresql-rectangular-12345 on ⬢ example-app
Press Ctrl+C to cancel

? Select the pool to update, or add a follower pool: (Use arrow keys)
  Leader: 4G-Performance 2 vCPU 4 GB MEM 2 instances starting at ~$0.208/hour ($150/month) each
❯ Follower follower-pool: 4G-Performance 2 vCPU 4 GB MEM 3 instances starting at ~$0.208/hour ($150/month) each
  ──────────────
  Add a follower pool
  Exit

? What do you want to do?: (Use arrow keys)
  Change pool level
  Update number of instances
> Destroy pool
  ──────────────
  Go back

 ›   Warning: Destructive Action
 ›   This command will affect the app ⬢ example-app

? To proceed, type example-app or re-run this command with --confirm example-app: example-app
Destroying follower pool follower-pool on ⛁ postgresql-rectangular-12345... done

Configure Storage Quotas and Thresholds

See Heroku Postgres Advanced Quotas for more information on storage in Advanced databases.

To configure storage thresholds and an enforcement action on your database, run the data:pg:quotas:update command. This example sets a warning threshold of 12 GB, a critical threshold of 15 GB, and an enforcement action of notifying if exceeding the critical threshold:

$ heroku data:pg:quotas:update HEROKU_POSTGRESQL_COBALT -a example-app --type storage --warning 12 --critical 15 --enforcement-action notify
Updating storage quota on ⛁ COBALT... done
=== Storage

Warning:            12.00 GB
Critical:           15.00 GB
Enforcement Action: Notify
Enforcement:        1.07 GB / 15.00 GB (7.13 %) (Within configured quotas)

After setting your quotas, you can view your quotas with the data:pg:quotas command:

$ heroku data:pg:quotas HEROKU_POSTGRESQL_COBALT -a example-app
=== Storage

Warning:            12.00 GB
Critical:           15.00 GB
Enforcement Action: Notify
Enforcement:        1.07 GB / 15.00 (7.13 %) (Within configured quotas)

View Database Logs and Metrics

See Heroku Postgres Metrics Logs for more information on logs and metrics in Advanced databases.

You can view Postgres Advanced databases logs in the Heroku CLI. For Common Runtime Advanced databases, you can run heroku logs -t to see your application router and database logs. To only see the database logs, specify with the -d or --dyno-name= flags and the postgres type:

$ heroku logs -a example-app -d postgres

2026-05-18T05:16:23.000000+00:00 app[postgres]: [HEROKU_POSTGRESQL_TEAL] instance=i53j2qpjrvs6ie sql_error_code=00000 time_ms="2026-05-18 05:16:23.328" pid="4004" proc_start_time="2026-05-18 05:12:55 UTC" session_id="6a033567.fa4" vtid="251/0" tid="0" log_line="7" database="db3d6h3eloda95" connection_source="85.222.134.3(44069)" user="u6c0nr7v6o2mfl" application_name="psql interactive" LOG: duration: 3012.504 ms  statement: SELECT subject, category FROM (...);

Heroku Postgres Advanced databases emit metrics-to-logs (l2met) with metrics for the cluster, instance pool and instances. To only see the database metrics logs, specify with the -d or --dyno-name= flags and the heroku-postgres type:

$ heroku logs -a example-app -d heroku-postgres

2026-05-18T14:21:47.000000+00:00 app[heroku-postgres]: [cluster] addon=postgresql-horizontal-12345 sample#current_transaction=8373348 sample#db_size=8067731 sample#db-max-size=100000000000000 sample#db-size-percentage-used=0.00000 sample#tables=0 sample#index-cache-hit-rate=0 sample#table-cache-hit-rate=0 sample#read-iops=0 sample#write-iops=7.5369
2026-05-18T14:21:47.000000+00:00 app[heroku-postgres]: [instance-pool] addon=postgresql-horizontal-12345 instance-pool=leader sample#active-connections=0 sample#max-connections=400 sample#connections-percentage-used=0.00000 sample#load-avg-1m=0.3 sample#load-avg-5m=0.46 sample#load-avg-15m=0.43 sample#memory-total-avg=3940632.0 sample#memory-freeable-avg=2455748.0 sample#memory-cached-avg=2512128.0
2026-05-18T14:21:47.000000+00:00 app[heroku-postgres]: [instance] addon=postgresql-horizontal-12345 instance-pool=leader role=writer instance=i53j2qpjrvs6ie service-available=true sample#load-avg-1m=0.3 sample#load-avg-5m=0.46 sample#load-avg-15m=0.43 sample#memory-total=3940632 sample#memory-freeable=2455748 sample#memory-cached=2512128

For Private Space Advanced databases, you must configure a log drain to view logs. See Log Drains for more information.

Destroy the Database

To destroy your Advanced database, run the command:

$ heroku data:pg:destroy postgresql-rectangular-12345 -a example-app --confirm example-app
Destroying postgresql-rectangular-12345 on ⬢ example-app... done
We successfully destroyed your database.

Next Steps

See the Heroku Postgres Advanced category for more information on Advanced databases.