Last updated January 11, 2023

The PostgreSQL project releases new major versions on a yearly basis. Heroku Postgres supports each major version shortly after its release.

Version Support

Heroku Postgres supports at least 3 major versions at a given time. Heroku currently offers Postgres version 14 as the default. Currently supported versions include:

Users are required to upgrade roughly one time every three years. However, you can upgrade your database PostgreSQL version at any point to gain the benefits of the latest version.

The deprecation process for PostgreSQL versions in Heroku Postgres starts 1 year before its EOL date. Deprecation processes are announced via the Changelog. Instances on deprecated versions are subject to forced upgrade attempts, database access restrictions, and database deletion for non-compliance.

To create a database on an older, supported PostgreSQL version use the –version flag with the addons:create command.

Migration of Deprecated Databases

The PostgreSQL project stops supporting a major version five years after its initial release. Heroku Postgres deprecates these versions to ensure no databases run on an unsupported major version of PostgreSQL.

Heroku highly recommends that you perform the version upgrade before support ends so that you can test compatibility, plan for unforeseen issues, and migrate your database on your own schedule.

Essential-Tier Databases

One (1) year before a version’s end of life (EOL) Heroku prevents provisioning new Essential-tier databases on the deprecated version.

At that time, Heroku starts migrating Essential-tier databases running on the deprecated versions to the last default version available.

Standard-Tier or Higher Databases

• One (1) year before a version’s end of life (EOL), Heroku notifies customers via email about the deprecation process for their affected databases.
• Six (6) months before EOL, Heroku prevents provisioning new Standard-tier or higher databases on the deprecated version. Creating forks and followers of existing databases is allowed.
• One (1) month before EOL, Heroku schedules forced upgrade maintenances for databases that are still running on a deprecated version.

Legacy Infrastructure

Heroku also occasionally deprecates old versions of its infrastructure for the following reasons:

• The operating system running beneath the database stops receiving security updates.
• Support for the operating system is no longer practical due to its age (required packages and patches are no longer available or difficult to support).
• The server instances are are impractical to support because they’re significantly different from Heroku’s current infrastructure.

To see if your database is running on legacy infrastructure, use pg:info:

$ heroku pg:info

=== DATABASE_URL, HEROKU_POSTGRESQL_IVORY_URL
Plan:                  Standard 0
Status:                Available
Data Size:             8.09 MB
Tables:                0
PG Version:            12.5
Connections:           7/120
Connection Pooling:    Available
Credentials:           1
Fork/Follow:           Available
Rollback:              earliest from 2021-01-24 18:59 UTC
Created:               2020-12-01 02:27
Region:                us
Data Encryption:       In Use
Continuous Protection: On
Forked From:           HEROKU_POSTGRESQL_SILVER
Maintenance:           not required
Maintenance window:    Wednesdays 21:30 to Thursdays 01:30 UTC
Add-on:                postgresql-cubed-48277