Upgrading the minor engine version of your ApsaraDB RDS for PostgreSQL instance delivers performance improvements, new features, and security fixes.
Upgrading the minor engine version restarts the instance, causing a brief connection interruption of approximately 30 seconds. Schedule upgrades during off-peak hours or make sure your application has an automatic reconnection mechanism.
For a full list of changes in each AliPG release, see Release notes for AliPG minor engine versions (PostgreSQL 14–17).
Usage notes
The upgrade is irreversible. You cannot downgrade the minor engine version after an upgrade.
Extension compatibility. Minor version upgrades typically do not cause compatibility issues, but extension upgrades might. If your instance uses the GanosBase extension, create a test instance using the restore data feature and validate compatibility on the test instance before upgrading your production instance.
PostGIS and GanosBase. After upgrading the minor engine version, manually upgrade the PostGIS or GanosBase extension if your service uses either of them. For more information, see GanosBaseGanosBaseGanosBaseGanosBaseGanosBaseGanosBaseUpgrade spatiotemporal engine extensions.
TimescaleDB. If your instance runs PostgreSQL 14 with a minor engine version earlier than 20230330 and uses TimescaleDB version 2.5.0 or earlier, run
ALTER EXTENSION timescaledb UPDATE;after upgrading to version 20230330 or later to continue using TimescaleDB.
Check the current minor engine version
| Method | How | Applies to |
|---|---|---|
| Console | Open the Basic Information page of the instance | Cloud disk instances only |
| SQL command | Connect to the instance and run show rds_release_date; | Cloud disk and local disk instances |
Upgrade the minor engine version manually
Instances that use local disks
Local disk instances do not support manual upgrades. Restarting the instance automatically upgrades it to the latest minor version. For more information, see Restart an instance.
If the instance is a primary instance with read-only instances attached, restart all read-only instances one by one first, then restart the primary instance. Restarting only the primary instance does not upgrade the minor engine version of the read-only instances.
Instances that use cloud disks
If the instance is a primary instance with read-only instances attached, you have two options:
Start the upgrade on the primary instance. All read-only instances are upgraded concurrently, then the primary instance is upgraded.
Upgrade the read-only instances one by one first, then upgrade the primary instance.
Go to the Instances page. In the top navigation bar, select the region where your instance resides. Find the instance and click its ID.
In the Configuration Information section, click Update Minor Engine Version.
In the dialog box, select a version under Latest Version, set the Update Time, and click OK.
The Latest Version string follows this format: rds.postgres.{major-version}.{AliPG-date}.{community-version}. For example, rds.postgres.1200.20220830.12.11 means:
| Segment | Value | Meaning |
|---|---|---|
rds | rds | RDS instance |
postgres | postgres | PostgreSQL database |
1200 | 1200 | PostgreSQL major version 12 |
20220830 | 20220830 | AliPG minor engine version date |
12.11 | 12.11 | PostgreSQL community minor version |
For details about each AliPG version, see Release notes for AliPG minor engine versions (PostgreSQL 14–17).
Configure automatic upgrades
Automatic upgrades are a supplementary method and do not guarantee that all instances are upgraded immediately. Monitor the engine version status on the Basic Information page and upgrade promptly to reduce exposure to risks from older versions. If you cancel a system-initiated upgrade task or miss upgrading to the latest stable version after receiving a console notification, you are responsible for any business interruptions or data loss that may occur. For more information, see Terms of Service.
Automatic minor engine version upgrades are supported only for instances that use cloud disks.
When you purchase an ApsaraDB RDS for PostgreSQL instance that uses cloud disks, the Minor Engine Version Update Policy defaults to Automatic Upgrade. When your version falls behind the latest, the system periodically schedules an operations and maintenance (O&M) task and notifies you by email or internal message. The upgrade runs within your configured maintenance window. Before the task starts, you can reschedule or cancel it from Event Management. For more information, see Scheduled events.
Change the upgrade policy
Go to the Instances page. In the top navigation bar, select the region where your instance resides. Find the instance and click its ID.
On the Basic Information page, find the Configuration Information section and locate the Automated Update of Minor Engine Version parameter.
Click Settings to the right of Automated Update of Minor Engine Version.
In the dialog box, select Automatic Upgrade or Manual Upgrade, then click OK.
FAQ
After upgrading, I get an error when accessing the PostGIS or GanosBase extension. What should I do?
After upgrading the minor engine version, manually upgrade the PostGIS or GanosBase extension. For steps, see Upgrade spatiotemporal engine extensions.
What PostGIS compatibility issues can occur after upgrading?
The following issues apply to instances running a minor engine version earlier than 20211031.
PostGIS 2.5.x
| Scenario | Impact |
|---|---|
| Upgrade only the minor engine version | Crash risk: ST_ClusterKMeans, ST_GeomFromKML, ST_AsKML may crash the database. Errors: ST_Buffer returns Invalid buffer parameter: uad_segs (accept: 'endcap', 'join', 'mitre_limit', 'miter_limit', 'quad_segs' and 'side')—change quadsegs to quad_segs to fix it. ST_Intersects returns ERROR: GetGenericCacheCollection: Could not find upper context with no workaround. Deleted functions: ST_Force_2D, ST_Locate_Along_Measure, ST_Estimated_Extent are removed. Behavior changes: ST_GeomFromGeoJSON defaults to SRID=4326; ST_AsGeoJSON reduces maxdecimaldigits from 16 to 9; MultiPoint syntax changes from MULTIPOINT(1 1,-1 1) to MULTIPOINT((1 1),(-1 1)). |
| Upgrade the minor engine version and the PostGIS extension | Deleted functions: ST_Force_2D, ST_Locate_Along_Measure, ST_Estimated_Extent are removed. Behavior changes: Same ST_GeomFromGeoJSON, ST_AsGeoJSON, and MultiPoint changes as above. |
PostGIS 3.1.x
| Scenario | Impact |
|---|---|
| Upgrade only the minor engine version | Crash risk: ST_ClusterKMeans may crash the database. Behavior change: MultiPoint syntax changes from MULTIPOINT(1 1,-1 1) to MULTIPOINT((1 1),(-1 1)). |
| Upgrade the minor engine version and the PostGIS extension | Behavior change: MultiPoint syntax changes from MULTIPOINT(1 1,-1 1) to MULTIPOINT((1 1),(-1 1)). |
API reference
Use the following API operations to manage minor engine version upgrades programmatically.
| API | Description |
|---|---|
| UpgradeDBInstanceKernelVersion | Upgrades the minor engine version of an instance |
| ModifyDBInstanceAutoUpgradeMinorVersion | Sets the minor engine version upgrade policy to automatic or manual |
What's next
If your service uses PostGIS or GanosBase, upgrade the extension after the minor engine version upgrade. See Upgrade spatiotemporal engine extensions.
Review the changes in each release before upgrading. See Release notes for AliPG minor engine versions (PostgreSQL 14–17).