Upgrades and Patches

Performs database and load-balancer-related package upgrades.

Warning

A database upgrade is a risky operation and ClusterControl does not support an upgrade rollback operation. Please perform this activity on a test/staging cluster first before proceeding with the actual upgrade. Upgrades should only be performed when there is as little traffic as possible on the cluster. Performing a full database backup (or taking a full VM snapshot) before an upgrade will increase the chance of recovery in case a rollback is needed. Taking a backup (before the upgrade) or restoring a backup (to rollback) is not part of this particular upgrade job.

ClusterControl will perform the software upgrade based on what is available in the package repository for the particular vendor. Having said that, if the database vendor repository is not up-to-date, or can not be updated to the latest repository (e.g, non-Internet environment, or outbound connections behind a pre-configured HTTP proxy), ClusterControl will not be able to perform the upgrade since there will be no new packages appear in the server’s repository list.

Minor upgrade

MySQL-based clustersMariaDB-based clustersMongoDB Replica SetMongoDB Sharded ClusterPostgreSQL-based clustersTimescaleDB-based clustersRedis-based clusters

Performs minor software upgrades for database and load balancer software. Minor upgrade version formatting is notably different depending on the database type and vendor:

• MySQL/Percona Server for MySQL – 8.0.x to 8.0.y
• MariaDB – 11.4.x to 11.4.y
• MongoDB – 7.0.x to 7.0.y
• PostgreSQL/TimescaleDB/EntepriseDB – 16.x to 16.y
• Redis Cluster/Sentinel – 7.x to 7.y
• ProxySQL – 2.6.x to 2.6.y
• PgBouncer – 1.22.x to 1.22.y
• HAProxy – 2.1.x to 2.1.y
• MariaDB MaxScale – 22.08.x to 22.08.y

For a primary-replica replication setup, ClusterControl will perform the upgrade starting from the replica/secondary nodes and will eventually perform the upgrade on the primary node of a cluster (secondary first, primary last). During the eventual primary node upgrade, expect a service disruption to the database cluster service until the primary node is online again after restarting. For a multi-primary setup, ClusterControl will upgrade any database node in a random order, one node at a time. If a node fails to be upgraded, the upgrade job is aborted and manual intervention is required to recover or reinstall the node. Due to this fact, it is important to have a proper maintenance window, which should only be performed when there is as little traffic as possible to the cluster.

Feature	Description
Upgrade	Triggers an upgrade job using the corresponding package manager.
Check for upgrades	Triggers a job to check for any new versions of database-related packages. It is recommended to perform this operation before performing an actual upgrade.
Select nodes	Toggle all nodes that you want to upgrade. Clicking on Database nodes will select all nodes in that cluster.

Major upgrade

Performs major software upgrades for the database software. Only one major version upgrade is supported at a time, for example, from PostgreSQL 13.x to 14.x. At the moment, only PostgreSQL-based clusters are supported. If you want to upgrade from PostgreSQL 12.x to 14.x, you have to upgrade stage-by-stage to PostgreSQL 13.x first, followed by PostgreSQL 14.x.

For a primary-replica replication setup, ClusterControl will perform the upgrade starting from the replica/secondary nodes and will eventually perform the upgrade on the primary node of a cluster (secondary first, primary last). During the eventual primary node upgrade, expect a service disruption to the database cluster service until the primary node is online again after restarting. If a node fails to be upgraded, the upgrade job is aborted and manual intervention is required to recover or reinstall the node. Due to this fact, it is important to have a proper maintenance window, which should only be performed when there is as little traffic as possible to the cluster.

Feature	Description
Configuration
Vendor	Detected current database vendor. This is informational and not configurable.
Current version	Detected current database version. This is informational and not configurable.
Upgrade version	Available upgrade version. This is informational and not configurable. ClusterControl only allows one major version upgrade at a time.
Method	copy – This is the default method with pg_upgrade. The --copy option is used which will copy ‘files at a time’ which is faster than doing regular backup and restore. This requires disk storage capacity to hold both the old and the new files. Note that data stored in user-defined tablespaces is not being copied to the new cluster during an upgrade. It remains in its original file system location but is duplicated into a subdirectory indicating the version number of the new cluster. To manually relocate files that are stored in a tablespace after upgrading, move the files to the new location and update the symbolic links to point to the files. link – This method uses the --link option with pg_ugprade. Hard links will be used instead of copying (--copy) files which is faster and requires no extra disk storage. It is crucial to refrain from starting the old cluster after this step to avert any potential data corruption with the new cluster since they share the data. pgdumpall – This is an alternative method to pg_upgrade and uses pgdumpall to copy files by performing a backup on the old cluster and then restoring it on the new cluster. This requires disk storage capacity to hold the backup for the old and new files.
A major upgrade is performed at your own risk	Accept the disclaimer to proceed with the upgrade.
Advanced
Temporary master port	The temporary PostgreSQL port of the older version. ClusterControl will reconfigure the PostgreSQL port of the older instances to this port for the duration of the upgrade, since the common port 5432, will be taken over by the newer PostgreSQL instance after the upgrading job completes.
Temporary upgrade candidate port	The temporary PostgreSQL port of the newer version while the upgrade job is running. ClusterControl distinguishes every node with a “hostname:port” pair. This provides a temporary entity for the newer database instance for the duration of the upgrade before it takes over the actual PostgreSQL port. This port will be released after the upgrade job is completed.