Heroku Postgres Follower Databases

Last updated March 31, 2026

Database replication serves many purposes including increasing read throughput with a leader-follower configuration, additional availability with a hot standby, serving as a reporting database, and seamless migrations and upgrades. Though these strategies all serve different purposes, they’re all based on the ability to create and manage copies of a lead database. On Heroku Postgres, this functionality is exposed as the follow feature.

A database follower is a read-only copy of the leader database that stays up to date with the leader database data. As writes and other data modifications are committed in the leader database, the changes are streamed, in real time, to the follower databases.

Followers are only supported on Standard, Premium, and Private and Shield tier database plans. To upgrade from an Essential-tier plan to a plan in another tier, follow these instructions.

Followers, like all Heroku Postgres databases, are charged on a pro-rated basis based on the plan of the follower.

You can also use heroku pg:psql with followers to safely connect and run queries against your data.

Create a Follower

A follower can be created for any Standard, Premium, Private, or Shield-tier database that is itself not a follower (that is, followers can’t be chained). Followers can’t be created for a period on newly forked databases (this applies to both explicit forks and forks created through unfollow). The exact timeframe varies depending on the size of the database to be followed and is typically between a few minutes and a few hours.

The following table summarizes where and how you can implement followers:

Leader Follower Allowed
Common Runtime Common Runtime Yes
Common Runtime Private Space Yes
Private Space Common Runtime Yes 1
Private Space Private Space (same Leader’s Space) Yes
Private Space Private Space (different from Leader’s Space) Yes 1
Shield Private Space Shield Private Space (same Leader’s Space) Yes
Shield Private Space Shield Private Space (different from Leader’s Space) Yes 2
Shield Private Space Private Space / Common Runtime No

Notes:

  1. Enable Trusted IP ranges for data services to avoid follower lag
  2. Replication is subject to lag as Trusted IP ranges for data services aren’t currently available for Shield Spaces

The follower must accommodate the current data volume of the leader database. If you attempt to create a follower that can’t accommodate the data volume, the follower creation fails with an error message that indicates the minimum plan needed.

The number of followers that you can create from a single leader is limited. The exact limit depends on your plan, the number of data connectors, and the number of existing followers. You see an error message if you try to create a follower that exceeds the calculated limit. In general, it’s not recommended to create more than 10 followers on the same leader.

When a database is ready to support followers, that information shows in heroku pg:info under the Fork/Follow details. heroku pg:info also lists the followers for a leader database and indicates the leader database of a follower:

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

Plan:                  Standard 0
…
Fork/Follow:           Available
…
Followers:             HEROKU_POSTGRESQL_IVORY
…
Add-on:                postgresql-octagonal-85179

=== HEROKU_POSTGRESQL_IVORY_URL

Plan:                  Standard 0
…
Fork/Follow:           Unavailable on followers
…
Following:             DATABASE
Add-on:                postgresql-elliptical-24253

The lag between a leader and follower databases varies greatly depending on the amount and frequency of data updates. It’s possible for long-running queries on the follower to impact replication and increase your replication lag time, though after those queries are done your follower catches up. Under normal usage, it’s common for your follower to be within a few seconds or less of your leader.

Create a follower database by provisioning a new heroku-postgresql Standard-tier or higher add-on database and specify the leader database to follow with the --follow flag. The flag can take either the add-on name, the config var name of the database on the same app, an argument of the form appname::HEROKU_POSTGRES_COLOR_URL, or the full URL of any Heroku Postgres database.

Followers don’t have to be in the same database plan as their leader. Followers can be up to 4 plans below their leader’s plan. It’s recommended that unless you’re downgrading plans, a follower be created using the same or higher plan than the leader database.

$ heroku addons:create heroku-postgresql:standard-0 -a example-app -- --follow HEROKU_POSTGRESQL_PURPLE_URL
Creating heroku-postgresql:standard-0 on ⬢ example-app... ~$0.069/hour (max $50/month)
The database should be available in 3-5 minutes.
Use `heroku pg:wait` to track status.
postgresql-elliptical-24253 is being created in the background. The app will restart when complete...
Use heroku addons:info postgresql-elliptical-24253 to check creation progress
Use heroku addons:docs heroku-postgresql to view documentation

Preparing a follower can take anywhere from several minutes to several hours, depending on the size of your dataset. The heroku pg:wait command outputs the provisioning status of any new databases.

$ heroku pg:wait
Waiting for database HEROKU_POSTGRESQL_IVORY_URL... available

Follower databases on Premium, Private, and Shield tier plans don’t have a hidden standby until they unfollow their leader database. If high availability is required on follower databases, set up multiple followers.

Creating a Follower via the Heroku Data Dashboard

You can also create followers through the web dashboard:

  1. Go to the Datastores tab on the Heroku Dashboard.
  2. Use the search and select the database you want to create a follower from.
  3. Click the Durability tab.
  4. Scroll down to the Followers section.
  5. Click the Add a Follower button.
  6. Choose the plan for the follower. Review the Create a follower section for notes on selecting a plan size.
  7. Click the Add follower button.

The dashboard shows the status of the follower database and updates when the provisioning is complete.

Create a Follower on a Different App

Followers don’t need to be tied to the same application. With shareable add-ons, you can provision the leader and follower databases on separate applications. The steps to create a follower on a different app are the same as the steps outlined for creating a follower on the same application with a few slight differences.

Use heroku addons:create to create the follower on the app that you want it attached to. To reference the leader database that you want the new database to follow, you can use the leader’s add-on name, the attachment name for the leader’s app, or the full connection string of the leader’s database.

For example, if a second application is called other-app and you want to have a follower attached to it using the main database from example-app, create a follower identifying the leader with its add-on name:

$ heroku addons:create heroku-postgresql:standard-0 --as OTHER_APP_FOLLOWER -a other-app -- --follow postgresql-octagonal-85179

Or alternatively, identifying the leader with its app’s attachment name:

$ heroku addons:create heroku-postgresql:standard-0 --as OTHER_APP_FOLLOWER -a other-app -- --follow example-app::DATABASE_URL

Using Custom Credentials on a Follower

Follower databases inherit the credentials that exist on their leader database.

Attach a specific credential from a follower database to an app with the heroku addons:attach command, specifying the follower database’s add-on or attachment name, and the name of the credential to attach:

$ heroku addons:attach postgresql-elliptical-24253 --credential analytics_cred --as ANALYTICS_FOLLOWER -a example-app
Attaching analytics_cred of postgresql-elliptical-24253 as ANALYTICS_FOLLOWER to example-app... done
Setting ANALYTICS_FOLLOWER config vars and restarting example-app... done, v852

Unfollow

The heroku pg:unfollow command stops the follower from receiving updates from its leader database and transforms it into an independent read/write database containing all of the data received up to that point. This command creates a database fork.

$ heroku pg:unfollow HEROKU_POSTGRESQL_IVORY_URL -a example-app
!    HEROKU_POSTGRESQL_IVORY_URL will become writable and no longer
!    follow DATABASE. This cannot be undone.

!    WARNING: Potentially 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
Unfollowing... done

Unfollowing a database isn’t the same as deprovisioning it. A database that unfollows its leader becomes an independent fork database and you’re still charged for the add-on. To deprovision a database, use the heroku addons:destroy command.

Database Upgrades and Migrations with Changeovers

In addition to providing data redundancy, followers can also be used to change database plans, underlying infrastructure, or minor versions with minimal downtime. To update your database with a follower, see this guide on updating Heroku Postgres.

Monitoring Followers

Because followers are asynchronously updated, they can be behind their leader by some number of commits. You can view the number of commits your follower is behind by running heroku pg:info.

Use the database metrics of the Heroku Postgres metrics logs, including the sample#follower-lag-commits metric, to monitor follower lag for your database.

If your follower is increasing in the number of commits it’s behind, it can be due to long-running transactions on your database. Run the heroku pg:ps command to get currently running transactions. Then if any transactions or queries have been running for longer than expected, you can cancel them with:

$ heroku pg:kill PROCESSID

If you can’t cancel them, you can try terminating their specific database process with the -f (force) parameter:

$ heroku pg:kill -f PROCESSID

Heroku Postgres has an automated monitoring system for followers. It checks if the follower is more than 64 write-ahead log segments (1024 MB) behind. If the lag is caused by long-running transactions/queries, we notify you via email that you have some transactions/queries that are causing the lag. If the situation doesn’t improve after one hour, we terminate any long-running transactions/queries automatically. You see a log entry of terminating connection due to administrator command for terminated transactions/queries.

High Availability with Followers

As a general practice, use a hot standby to achieve high availability in Heroku Postgres:

  • For primary Standard databases, create your own standby by adding a follower. Even if not being actively used as a read replica, creating a follower ensures that you have it available for manual promotion in situations where the primary database becomes corrupted or unavailable.
  • Primary databases on Heroku Postgres Premium, Private, and Shield plans have the HA feature with automated failover which creates a hidden standby for you. There’s no need to create a follower to achieve high availability.

Follower databases don’t have a hidden standby. If you require high availability on a follower itself, in addition to the primary database, provision multiple followers.

Follower databases are guaranteed to be provisioned on geographically separate infrastructure than the primary database.

Manually Promoting Followers in a Failover Event

Heroku doesn’t automatically promote an existing follower database when the primary database is corrupt or inaccessible. For Standard databases, Heroku Postgres’ monitoring system starts its automated remediation procedures to bring the database back online.

If high availability is required, use a Premium, Private, or Shield-tier plan that offers HA.

Performing a manual database failover to an existing follower is the same process as a database migration starting with the enter maintenance mode step.

Distributing App Reads to Followers

Heroku allows you to easily horizontally scale your app by adding additional dynos to meet capacity. Similarly, as detailed earlier, Heroku Postgres allows you to horizontally scale your database by adding read-only followers to the lead database. While these followers are great for analytical purposes, you can also use them via your application for handling read-only queries to your data. This type of architecture can be used to improve app performance as well as work around Heroku Postgres connection limits.

Redirecting your app’s read operations to one or more followers requires changes at the code level of your app. Since each app on Heroku is different, it’s not possible to recommend how to proceed. If your app is built using a framework, it’s likely the framework has support for using multiple databases. In other cases, there are third-party libraries available to help with the handling of multiple databases. In some cases, especially as your app gets more complex, writing custom code is necessary.