Heroku Postgres upgrade results in unexplained connection timeouts after dyno restart

Answer to the Core Question

Heroku currently performs a very light protocol‑compatibility check during heroku pg:upgrade. It only compares the target PostgreSQL version with the minimum supported version declared in the buildpack metadata. If the bundled client library is older than the new server protocol, the upgrade proceeds without a warning, and the application may experience SSL handshake failures or connection timeouts after the dyno restarts.

So, to answer directly:

• Heroku’s heuristic is a minimal version comparison; it does not flag or block upgrades when the client library is too old.
• At present, Heroku does not emit an explicit warning for this scenario.
• Users can verify compatibility without upgrading by running a dry‑run and by performing a one‑off dyno test that attempts a database connection with the current client library.

Likely Explanation vs. Confirmed Facts

• Likely Explanation: The client library bundled by the buildpack (or supplied by a custom buildpack) does not support the protocol changes introduced in PostgreSQL 15+. After the upgrade, the application’s connection string still points to the same database, but the older client cannot negotiate the new protocol, causing SSL or timeout errors.
• Confirmed Fact: Heroku’s heroku pg:upgrade --dry-run simulates the upgrade and can surface protocol mismatches, but it is not exhaustive. The platform does not automatically update buildpack‑bundled client libraries.

Steps to Verify Compatibility Before Upgrading

1. Check Current Server Version

   heroku pg:info --json
   

   Note the current_version field.

2. Identify Client Library Version
   • For Java: mvn dependency:list | grep postgresql
   • For Python: pip freeze | grep psycopg2
   • For Ruby: bundle list | grep pg
3. Run a Dry‑Run Upgrade

   heroku pg:upgrade --dry-run
   

   Review the output for any "protocol mismatch" or "client version too old" messages.

4. Test Connection in a One‑Off Dyno

   heroku run 
   # e.g., heroku run java -cp target/classes com.example.Main
   

   Then tail the logs:

   heroku logs --tail
   

   Look for SSL handshake failures, timeout warnings, or failed connection attempts.

5. Optional: Use a Newer Client Locally

   Clone the app’s repository, update the client dependency to the latest supported version, rebuild, and run the same connection test locally or in a staging dyno.

What to Do If a Warning Is Needed

Given the observed post‑upgrade failures, a reasonable enhancement would be for Heroku to emit a warning when the detected client library version is older than the target PostgreSQL version. The warning could be presented during the upgrade prompt or logged as a post‑upgrade advisory.

Missing Diagnostic Detail

To refine the recommendation, could you confirm whether your application uses a custom buildpack that bundles a PostgreSQL client library? If so, the current compatibility heuristic may not apply.