How to Upgrade a Vultr Managed Database for PostgreSQL v13 to a Stable Version

PostgreSQL v13 will reach End of Life (EOL) in mid-November 2025, meaning it will no longer receive security updates, bug fixes, or performance improvements. Running an unsupported version leaves your applications at risk and may impact service stability.

To maintain a secure and reliable environment, you should upgrade your Vultr Managed Database for PostgreSQL v13 to a newer, supported version before the EOL date.

If you do not take action:

• You will lose the ability to fork v13 databases for safe upgrade testing.
• The platform will attempt an automatic upgrade, which may fail due to incompatibilities or extension issues.
• Failed automatic upgrades may lead to downtime, forced service shutdown, and in the worst case, permanent data loss.

Follow this guide to safely upgrade your PostgreSQL v13 clusters to the latest supported version, ensuring your databases remain stable, secure, and fully operational.

Prerequisites

Before you begin, ensure you:

• Have access to an existing Vultr Managed Database for PostgreSQL v13.
• Create a backup of all databases using pg_dump.

Fork Your Existing PostgreSQL v13 Cluster

Before starting the upgrade process, you should create a fork of your existing PostgreSQL v13 cluster. Forking creates an independent copy of your database, which allows you to test the upgrade without impacting your production workloads. This step is important because it ensures that the upgrade process can be validated in advance, potential issues with extensions or large datasets can be identified, and your applications can be tested against the new PostgreSQL version under realistic conditions.

1. Log in to the Vultr Customer Portal.
2. Navigate to the Databases section under Products.
3. From the list of available databases, locate and select the PostgreSQL v13 database that you want to upgrade.
4. Under the Overview tab, find the Actions menu and choose the option Fork Database Cluster.
5. In the Choose a state section, select Latest Backup, which typically corresponds to a backup created within the last hour.
6. Review the Server Configuration section, which automatically matches the plan of your original cluster.
7. In the Server Location section, select the region where the forked cluster should be deployed, typically the same region as the original cluster.
8. If your existing database is connected through a VPC network, make sure to select the same VPC for the forked cluster.
9. Provide a descriptive label for the forked cluster, and then click Deploy Now to begin the provisioning process.

Upgrade the Forked Cluster

After creating a fork of your PostgreSQL v13 database, the next step is to upgrade the forked cluster. Performing the upgrade on a fork ensures that you can safely validate compatibility, test extensions, and verify application performance before applying changes to the production database.

1. Return to the Databases section in the Vultr Customer Portal.
2. Select the forked PostgreSQL v13 cluster you created in the previous step.
3. Open the Settings tab, then choose Upgrade Version from the left hand menu.
4. From the list of available versions, select the next major version. For example, upgrade from v13 to v14.
5. Wait until the primary database node completes the upgrade and becomes accessible. Read replicas in the forked cluster are upgraded automatically, so no manual intervention is required.
6. Continue upgrading one major version at a time until you reach the latest supported stable release (for example, v17).

Test the Upgraded Cluster

After upgrading the forked cluster to the latest supported PostgreSQL version, it is important to test the cluster before applying changes to your production environment. Testing ensures that your applications remain compatible, performance is acceptable, and any potential issues are discovered early.

1. Begin by testing under a realistic workload. If possible, connect the upgraded cluster to a staging or development environment that mirrors your production setup. Monitor query execution, latency, and overall application stability.

2. Use the pgbench tool to benchmark performance and compare results with your original PostgreSQL v13 cluster.

3. Connect to the upgraded database using psql.

   console Copy

   $ psql postgres://vultradmin:<password>@<host.vultrdb.com>:<port>/defaultdb
   

4. Enable the pg_stat_statements extension to collect query execution statistics.

   psql Copy

   defaultdb=> CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
   

5. Run the following query to identify the five slowest queries, which may help detect performance regressions after the upgrade.

   psql Copy

   defaultdb=> SELECT query,
                   calls,
                   total_exec_time,
                   mean_exec_time
               FROM pg_stat_statements
               ORDER BY mean_exec_time DESC
               LIMIT 5;
   

6. Validate all required extensions are installed as some extensions may change behavior or require upgrades between major PostgreSQL versions.

   psql Copy

   defaultdb=> \dx
   

   Ensure every required extension is installed and at the correct version.

7. Check replication status if your cluster includes read replicas.

   psql Copy

   defaultdb=> SELECT client_addr,
               state,
               sync_state,
               write_lag,
               flush_lag,
               replay_lag
           FROM pg_stat_replication;
   

   Output:

   client_addr             |   state   | sync_state |    write_lag    |    flush_lag    |   replay_lag    
   ------------------------+-----------+------------+-----------------+-----------------+-----------------
                           | streaming | async      | 00:00:01.00131  | 00:00:43.743436 | 00:55:32.078504
   fda7:a938:5bfe:5fa6:... | streaming | async      | 00:00:00.001282 | 00:00:00.001575 | 00:00:00.001738

   In the above output 2nd row is the replica node replication status:

   • fda7:a938:5bfe:5fa6:...: The IPv6 address of your read replica. This shows which node is connected.
   • streaming: Replication is active. The replica is continuously receiving WAL (write-ahead log) records from the primary.
   • async: The replica is asynchronous. This means the primary doesn’t wait for the replica to acknowledge writes before committing transactions. If the primary crashes, the replica might be missing the very latest transactions.
   • write_lag = 00:00:00.001282 (~1.2 ms): Time between WAL being generated on the primary and received by the replica. Almost instant.
   • flush_lag = 00:00:00.001575 (~1.6 ms): Time it takes for the replica to write that WAL to disk after receiving it.
   • replay_lag = 00:00:00.001738 (~1.7 ms): Time it takes for the replica to actually apply (replay) the WAL changes into the database.

   Replication is considered healthy when the write_lag, flush_lag, and replay_lag values are close to zero.

8. Review database logs for warnings or errors that may indicate compatibility issues introduced by the new version.

Upgrade the Primary PostgreSQL Cluster

Upgrading the primary PostgreSQL cluster is the most important stage of the process, as it directly affects production workloads. To safeguard against issues, you should first add a read replica and confirm that replication is healthy. This replica provides an additional layer of protection, helping to reduce the risk of data loss if the primary node experiences problems during the upgrade. The upgrade itself must be performed step by step across major versions, and because the primary node will be unavailable during the operation, it is best scheduled during a maintenance window or a period of low traffic to minimize disruption.

Add a Read Replica

Before beginning the upgrade, it is recommended that you create a read-only replica. Large databases may require significant time to upgrade, during which the primary database will not be accessible. Having a replica ensures that your data remains available for read operations throughout the process. In addition, the replica acts as a safeguard against potential data loss, as it can serve as a fallback if the primary node experiences issues before the upgrade is completed.

1. Navigate to the Databases section under Products.

2. From the list of available databases, select the primary PostgreSQL cluster that you intend to upgrade.

3. In the Overview tab, locate the Actions menu and choose Add Read-Only Replica Node.

4. In the Server Location section, select the same region as the primary cluster.

5. Provide a descriptive label for the replica and click Deploy Now to begin provisioning.

6. Wait until the read replica becomes available.

7. After the replica is accessible, connect to the primary database using psql.

   console Copy

   $ psql postgres://vultradmin:<password>@<host.vultrdb.com>:<port>/defaultdb
   

8. Verify that there is no replication lag between the primary and replica node.

   psql Copy

   defaultdb=> SELECT client_addr,
               state,
               sync_state,
               write_lag,
               flush_lag,
               replay_lag
           FROM pg_stat_replication;
   

   Confirm that replication lag remains near zero.

Upgrade the Primary Cluster

Upgrading the cluster advances the primary database to a newer PostgreSQL version. This operation is performed in place and affects production availability, so it should be scheduled carefully.

Important considerations before upgrading:

• The upgrade is applied immediately once started.
• Downgrading to the previous version is not possible.
• Backups created on older PostgreSQL versions cannot be used for PITR. Only backups generated after the upgrade are valid for recovery.
• Expect downtime during the primary node upgrade. Plan this during a maintenance window or a low-traffic period.

1. Navigate back to the Databases section.
2. Select your primary PostgreSQL cluster.
3. Open the Settings tab, then choose Upgrade Version from the left menu.
4. Select the next available version. Major version upgrades must be performed sequentially (for example, v13 → v14 → v15 → v16 → v17). Skipping versions may corrupt the cluster.
5. When you select a version, the system performs a compatibility check.
6. After the compatibility check succeeds, click Submit to begin the upgrade. Any failover replicas are removed at this stage.
7. The upgrade duration depends on the size of your data and the workload on the cluster.
8. Wait until the primary node becomes accessible after the upgrade.
9. After the primary upgrade completes, a new full backup is initiated for the cluster. After this backup is ready, new failover replica nodes are provisioned.
10. Read replicas are upgraded automatically after the primary node is available. Ensure all replicas are accessible before proceeding to next upgrade.
11. After the upgrade, ANALYZE is automatically run on all tables to refresh statistics and optimize query performance. No manual action is required.
12. After the upgrade is completed, validate the upgraded primary cluster using the same tests performed on the forked cluster. This includes benchmarking with pgbench, checking query performance with pg_stat_statements, verifying required extensions, monitoring replication for read replicas, and reviewing database logs.

Conclusion

You have successfully upgraded your PostgreSQL cluster from v13 to the latest supported version by creating a forked cluster for safe testing, adding and verifying read replicas to minimize risk, and performing sequential major version upgrades. The upgraded cluster has been validated with benchmarks, query analysis, and replication checks to ensure applications, extensions, and queries function as expected.

For a detailed overview of changes, new features, and improvements in each PostgreSQL version, refer to the official PostgreSQL Release Notes.