Heroku Postgres Upgrade Guide: Simplify Your Move to Version 17

If you’ve ever deployed an app on Heroku, chances are you’ve used Heroku Postgres — our fully managed, reliable, and scalable Postgres database service. It’s the backbone for millions of applications, from weekend side projects to enterprise-grade systems running in production.

But Postgres, like all software, continues to evolve. With new versions released each year, you gain access to performance enhancements, critical security updates, and powerful new features. Keeping your database up to date isn’t just good practice — it’s essential for long-term stability and success.

That’s why we’re thrilled to share that Postgres 17 is now available on Heroku. And with our newly simplified upgrade process, keeping your database current has never been easier. There’s no better time to plan your next upgrade and take full advantage of everything Postgres 17 has to offer.

What is Heroku Postgres?

Heroku Postgres is a managed Postgres service built into the Heroku platform. It handles provisioning, maintenance, backups, high availability, and monitoring so that customers can focus on building engaging data-driven applications, instead of managing infrastructure.

Why upgrading your Postgres version matters

There are several important reasons for why upgrading your Postgres database is necessary,

• Security: Postgres regularly releases security updates to patch vulnerabilities. Running an outdated version could expose your database to known security risks. Once a version is unsupported, the Postgres Community won’t have any more security releases for that version.
• Bug Fixes: Each new version includes fixes for bugs and issues found in previous versions.
• Performance Improvements: Newer versions often include performance optimizations, better query planning, and improved resource utilization.
• New Features: Postgres releases bring new features and capabilities that can enhance your database’s functionality. For example:
  • Better parallel query execution
  • Improved indexing options
  • Enhanced monitoring capabilities
  • New data types and functions
• Compatibility: Staying current helps maintain compatibility with other tools, libraries, and applications that interact with your database.

The backstory: Our Postgres version support & deprecation policy

At Heroku, we follow a well-defined lifecycle for Postgres versions:

• Each major version is supported for a set period — currently three years.
• When a version approaches end-of-support, we begin our deprecation process — announcing an upcoming removal from the platform and stopping new provisioning.
• When deprecation is announced, we give customers advance notice and time to upgrade manually.
• If no action is taken, we then automatically upgrade databases still on unsupported versions, ensuring security and platform stability.

What we learned

Our internal upgrade automation has quietly and successfully upgraded tens of thousands of databases each year leading many customers to ask:

That demand inspired the improved pg:upgrade CLI experience — a safer, more transparent, and self-service version of our proven internal tools. Now, all Heroku Postgres users can benefit from the same automation and built-in checks that power our large-scale upgrade process.

Visit our devcenter for more details on how Heroku manages Postgres version support and deprecation timelines.

Introducing new pg:upgrade commands

We’re rolling out five new heroku pg:upgrade:* commands that give you more control, visibility, and confidence during Postgres version upgrades:

pg:upgrade:prepare – Schedule a Postgres upgrade for Standard-tier and higher leader databases during your next maintenance window.

pg:upgrade:run – Trigger an upgrade manually. Perfect to start an upgrade immediately on Essential-tier databases and follower databases, or run a prepared upgrade before the next scheduled maintenance window on a Standard-tier or higher database.

pg:upgrade:cancel – Cancel a scheduled upgrade (before it starts running).

pg:upgrade:dryrun – Simulate an upgrade on a Standard-tier or higher database using a follower to preview the upgrade experience and detect any potential issues — no impact on your production database.

pg:upgrade:wait – Track the progress of your upgrade in real time.

You’ll receive email notifications at every key stage:

• When the upgrade is scheduled, running, cancelled and completed (successfully or not).
• After a dry run completes, with a summary of the results and any potential issues detected.

Upgrading is now a simple 1-step process

You might notice there are more commands available now, but upgrading your database has actually become much simpler — it’s now just a 1-step process!

Heroku handles what used to be multiple manual steps — provisioning a follower, entering maintenance mode, promoting, reattaching, exiting maintenance mode — all with a single workflow.

See the section below for the most efficient path based on your database tier.

Step-by-step: How to upgrade Heroku Postgres

Essential-tier database upgrades

To upgrade, just run:

heroku pg:upgrade:run HEROKU_POSTGRESQL_RED --app example app

That’s it — no preparation step required.

Note: If you don’t specify a version with --version, the upgrade will use the latest supported Postgres version on Heroku.

Standard-tier & higher database upgrades

We recommend this process for Standard-tier and higher, regardless of whether or not you have follower databases.

Step 0 – Optional (but recommended)

Run a test upgrade to detect any potential issues before upgrading your production database.

heroku pg:upgrade:dryrun HEROKU_POSTGRESQL_RED --app example-app

Then proceed with the actual upgrade in one simple step:

Step 1 – Prepare the upgrade

heroku pg:upgrade:prepare HEROKU_POSTGRESQL_RED --app example-app --version 17

This schedules the upgrade for your next maintenance window.

Note: If --version is not specified, we’ll automatically use the latest supported Postgres version on Heroku.

Use the following to track when the upgrade is scheduled and ready to run:

heroku pg:upgrade:wait HEROKU_POSTGRESQL_RED --app example-app

Step 2 (Optional) – Manually run the upgrade

heroku pg:upgrade:run HEROKU_POSTGRESQL_RED --app example-app

This will upgrade your leader database and its follower(s) automatically.

Track the progress until completion with:

heroku pg:upgrade:wait HEROKU_POSTGRESQL_RED --app example-app

Tip: If you don’t manually run this command, the upgrade will be run automatically during the scheduled maintenance window. You can view your app’s maintenance window and scheduled maintenances by running:

heroku pg:info HEROKU_POSTGRESQL_RED --app example-app

For more information on maintenance windows, check out the Heroku Postgres Maintenance documentation.

Benefits of the new upgrade mechanism

• The new upgrade operates in-place using an internal replica, simplifying the process, removing the need to manage a separate follower add-on, and minimizing the risk of data loss or inconsistencies by managing database access internally throughout the upgrade.
• Using this automation will reduce downtime to about 5-10 minutes for a typical upgrade.
• When you upgrade your leader database, any followers are automatically upgraded – no need to recreate or manually reattach followers.
• Your app’s DATABASE_URL and other config_vars remain unchanged after the upgrade, ensuring your application continues to operate without any reconfiguration.
• The same simple steps apply to upgrading databases with Streaming Data Connectors, replacing what used to require at least 8 manual steps as outlined here.
• If we detect a known issue with your data/schema during the upgrade, you’ll receive an email with remediation steps to help you complete the upgrade.
• If the issue is unexpected or cannot be resolved automatically, we’ll prompt you to open a support ticket so our team can help troubleshoot.
• In all cases, your database remains available, and user access is restored once the upgrade process completes — whether it finishes successfully or is automatically aborted for safety.
• Want added peace of mind? Run a test upgrade in advance using heroku pg:upgrade:dryrun. This simulates the upgrade on a copy of your database and highlights potential issues before touching production.

The “old” follower upgrade approach

While we now recommend upgrading the leader database directly using the approach explained
above, customers who prefer the traditional flow can still use the follower upgrade approach.

To do this, you can continue to follow the steps as described here.

In order to run the upgrade, use:

heroku pg:upgrade:run HEROKU_POSTGRESQL_RED --app example-app

This approach has one notable benefit, your original leader database remains untouched during the upgrade, which allows for easier rollback, testing, or verification before promoting the upgraded follower.

Deprecation notice

The legacy heroku pg:upgrade command will be deprecated soon. To ensure a smoother, safer upgrade experience, we strongly recommend switching to the new heroku pg:upgrade:* subcommands.

If you continue to use the old command, you’ll receive tailored warnings and redirection to help guide you toward the updated flow. Make the switch today to take full advantage of the simplified, automated upgrade process.

Upgrading shouldn’t be a chore – it should be a habit

Upgrading your Postgres database shouldn’t be a last-minute scramble — it should be a routine habit. Regular upgrades help keep your applications secure and performant, while also giving you access to the latest features and improvements that drive innovation. By making upgrades a part of your development rhythm, you set your systems up for long-term stability, scalability, and success.

At Heroku, we’re focused on making the overall Postgres experience safer and more intuitive for developers. A key part of that is improving the upgrade process: with streamlined tooling, automation, and built-in safeguards, upgrading your Postgres version is now significantly faster and more reliable. All of this is designed to help you stay focused on what matters most – building and shipping great apps – while staying confident that your data layer is future-ready.