Upgrade the Major Version of the Database
Last updated: 2025-07-22 20:25:30
Overview and Advantages
TencentDB for PostgreSQL continuously offers new versions for customer use. New versions introduce more features, better performance, higher stability, and enhanced security. It is recommended that you reasonably plan based on business needs and upgrade the database major version as soon as possible.
TencentDB for PostgreSQL supports major version upgrades, and this tool has the following advantages:
Supports cross-version upgrades among PostgreSQL 9 to 17. Supports upgrade rehearsals.
The upgrade is performed on a read-only instance pulled from the original instance, with no impact to the original instance.
During a major version upgrade, the instance will become a read-only instance within a certain period. The duration of the instance read-only depends on the number of original instance objects and is irrelevant to the data scale.
During the statistics collection period, the instance will also become read-only. The duration of the read-only state depends on the amount of data.
After the original instance upgrade is completed, connection addresses, tags, monitoring, backup sets, and other information are fully retained.
Note:
It is strongly recommended that you initiate a drill before a major version upgrade so that you can more clearly estimate the instance read-only time.
Not currently supported to perform a major version upgrade on instances with transparent data encryption (TDE) enabled.
The major version cannot be downgraded. Currently, TencentDB for PostgreSQL major versions are fully compatible with old versions. It is recommended that you preferentially use higher versions.
Directions
Formal Major Version Upgrade
1. Log in to the PostgreSQL console. In the instance list, click Instance ID or Manage in the Operation column to enter the instance details page.
2. Click Version Upgrade to open the version upgrade operation page.
3. Click Upgrade Major Version to open the version upgrade page.
3.1 Target version
The system will provide all major versions available for upgrade at present, and users can choose. Only upgrading to the latest minor version under each major version is supported.
3.2 Upgrade time
During the upgrade process, there may be momentary disconnections and brief read-only periods. Therefore, business needs self-assessment of the operation time window. Immediate execution, specified time, or maintenance time are available options. For maintenance time settings, refer to Setting Instance Maintenance Time.
If the required preparations have been completed but the designated upgrade time has not yet arrived, the instance status will display as Waiting for Switch. You can directly start the upgrade by going to Instance List > Operation > Switch Immediately on the console.
3.3 Explanation of Statistical Information Collection
This operation mainly involves running ANALYZE on the primary instance and updating system statistics during the first launch of the database after the upgrade. Accurate statistical information ensures that the PostgreSQL query planner processes queries in the best way. Lack of statistical information may lead to errors in the query plan, which may decrease performance and occupy too much memory. The duration of generating statistical information depends on the size of the instance data volume. The instance will be read-only while generating statistical information.
3.4 Plugin upgrade setting
This operation mainly executes "ALTER EXTENSION UPDATE" on the database where plug-ins have been created after the upgrade is completed. Three upgrade times are supported:
Upgrade Time | Description |
Upgrade plugins before completing the major version upgrade. | Under this method, you need to check the plugin list of all databases and upgrade the plugins to the corresponding versions. The execution time is positively correlated with the number of databases and the number of plugins, which will extend the execution time of the entire major version upgrade. Please assess and then select. |
Upgrade plugins after completing the major version upgrade. | Under this method, the database will promptly resume read and write operations upon the completion of the major version upgrade, during which the plugins will undergo updates. However, during the plugin update period, the plugin features may become unavailable. When selecting this upgrade time, you need to evaluate whether your business will be affected. |
Do not upgrade the plugin version | Under this method, the database will promptly resume read and write operations upon completion of the major version upgrade, without automatically upgrading plugins. If needed, you can manually upgrade the plugins. When selecting this upgrade time, you need to evaluate whether your business will be affected. |
3.5 Whether to perform backup before the upgrade starts
When performing a major version upgrade, to ensure data recoverability, the system will automatically conduct two full backups by default. The backup type is upgrade backup:
Perform a full backup once before the upgrade starts, and perform it immediately at the commencement of the upgrade. If problems occur with the instance after a major version upgrade, users can use this backup to restore the database instance to the status of the previous version.
A full backup will be performed after the upgrade is completed. This backup is created immediately after new writes are allowed on the upgraded database instance.
Pre-upgrade backup supports two options:
Option | Description |
Yes | Default option. Backup will incur fees. For details, reference Backup Space Billing. Users can choose to delete it after upgrade verification is completed. The deletion policy for this backup file is also managed by the user-configured backup retention rules. If you want to extend the backup set retention time, enter the backup recovery interface and click  |
No | Select this option when the instance has backups that can be restored to the pre-upgrade state. Otherwise, it is not recommended. |
3.6 Task launch settings
Option | Description |
Check without initiating task | Only perform pre-upgrade checks, including instance running status, legitimacy of instance parameter settings, database connection check, etc., but do not initiate the task. Users can use this operation to pre-check the feasibility of the upgrade. |
Check and initiate task | Perform pre-upgrade checks, including instance running status, legitimacy of instance parameter settings, and database connection check. If the check passes, directly initiate the task. |
4. Click Submit to create an upgrade task. The instance status will change to Kernel Version Upgrading. Users can check the task status and system log in Upgrade Task List.
Drill Upgrade
To ensure the success rate of the upgrade, users can choose to conduct an upgrade drill first. The upgrade drill is based on the backup set of the current instance to clone a new instance first, then perform the upgrade on the new instance. After the upgrade is completed, a new instance will be generated. Users can choose to directly use the instance or delete it. Cloning to generate an instance will be billed normally in pay-as-you-go mode. For more details about the price, see Product Price. Specific operations are as follows:
1. Log in to the PostgreSQL console. In the instance list, click Instance ID or Manage in the Operation column to enter the instance details page.
2. Click Version Upgrade to open the version upgrade operation page.
3. Click Major Version Upgrade Drill to enter the rehearsal operation interface.
3.1 Cloned instance settings
3.2 Upgrade settings
Click Submit to initiate a drill task. If the original instance is postgres-*******, the system will create a new instance named postgres-*******-pre-upgrade-************** and complete the subsequent upgrade.
How It Works
To help you understand the system, and manage the major version upgrade time, this article shows the operations performed by the system during major version upgrade, as shown in the figure below:
The above figure uses the upgrade from PostgreSQL 10 to PostgreSQL 14 as an example, and detailed description of the backend system operating steps are as follows:
1. Precheck
Check if the instance state is running.
Check the validity of instance parameters.
Check if the target upgrade version is valid.
2. Create a read-only instance
Create a read-only instance of the source instance, to minimize the impact of upgrades on the original instance. Subsequent upgrade operations will be performed on this read-only instance.
3. Initialize the new version database
Create a blank directory, and initialize a new instance with the target version. This new instance only has a single node.
4. Stop the high version node, and set source instance master node to read-only.
Stop the new version instance, and set the source instance to read-only.
5. Promote the read-only instance to the master instance, and stop the process.
Promote the read-only instance to the master instance, and stop this instance.
6. Perform the upgrade
Perform the upgrade, export and import the metadata, and process data.
7. Launch the new version process, switch routes, build new standby machines, and reclaim the old nodes.
Launch the upgraded new version instance, switch the routing information of the original instance, and set up a secondary node for the new instance. In the end, clean up the environment to finish the task.
Note:
After the system upgrade is completed, carry out relevant verification to ensure the smooth operation of the business as follows:
Please run a business load test on the database after the upgrade.
Verify extension compatibility.
Verify parameter compatibility.
System Limits
If the instance has associated read-only instances, you need to delete the read-only instances before initiating the upgrade.
If the disk space usage of an instance exceeds its limit, initiating a major version upgrade will not be possible.
FAQs
Is the Major Version Downgrade supported?
The major version downgrade is not supported. The current TencentDB for PostgreSQL is forward compatible with major versions, a higher version is recommended.
Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No
Feedback