Upgrade the major engine version of an ApsaraDB RDS for PostgreSQL instance -

You can call the UpgradeDBInstanceMajorVersion operation to upgrade the major engine version of an ApsaraDB RDS for PostgreSQL instance.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

During an upgrade, ApsaraDB RDS retains the original instance and creates an instance that runs the new major engine version. You start to be charged for the new instance based on the pay-as-you-go billing method after the instance is created. The new instance does not inherit the reduced price that is offered to the original instance. Before you call this operation, make sure that you fully understand the billing methods and pricing of ApsaraDB RDS. You can decide whether to upgrade the major engine version based on your business requirements. For more information, see Billable items, billing methods, and pricing.

Before you upgrade the major engine version, you must call the UpgradeDBInstanceMajorVersionPrecheck operation to perform an upgrade check and then call the DescribeUpgradeMajorVersionPrecheckTask operation to query the upgrade check report. You can call the UpgradeDBInstanceMajorVersion operation only when the check result is Success.

Before you call this operation, make sure that the following requirements are met:

The original instance runs PostgreSQL 14, PostgreSQL 13, PostgreSQL 12, PostgreSQL 11, PostgreSQL 10, or PostgreSQL 9.4.
The original instance runs RDS High-availability Edition or RDS Basic Edition.
The original instance resides in a virtual private cloud (VPC). If the original instance resides in the classic network, you must migrate the instance to a VPC before you call this operation. For more information about how to view or change the network type of an instance, see Change the network type of an ApsaraDB RDS for PostgreSQL instance.
The original instance cannot be a read-only instance and cannot be created in a dedicated cluster.

An upgrade causes impacts such as a transient connection that lasts a few minutes. We recommend that you perform an upgrade during off-peak hours. Before you perform an upgrade, we recommend that you read the description in Upgrade the major engine version of an ApsaraDB RDS for PostgreSQL instance.

Request parameters


Parameter	Type	Required	Example	Description
Action	String	Yes	UpgradeDBInstanceMajorVersion	The operation that you want to perform. Set the value to UpgradeDBInstanceMajorVersion.
DBInstanceClass	String	No	pg.n2.medium.2c	The instance type of the new instance. The vCPU and memory specifications of the new instance must be higher than or equal to the vCPU and memory specifications of the original instance. For example, if the instance type of the original instance is `pg.n2.small.2c`, which provides 1 core and 2 GB of memory, the instance type of the new instance can be `pg.n2.medium.2c`, which provides 2 cores and 4 GB of memory. Note For more information about the supported instance types, see Primary ApsaraDB RDS for PostgreSQL instance types.
DBInstanceStorage	Integer	No	20	The storage capacity of the new instance. Unit: GB. Valid values if you use enhanced SSDs (ESSDs) of performance level 1 (PL1): 20 to 3,200 Valid values if you use ESSDs of PL2: 500 to 3,200 Valid values if you use ESSDs of PL3: 1,500 to 3,200 Note If the original instance uses local SSDs, you can reduce the storage capacity of the instance when you upgrade the major engine version of the instance. For more information about the minimum storage capacity, see Upgrade the major engine version of an ApsaraDB RDS for PostgreSQL instance.
PayType	String	Yes	Postpaid	The billing method of the new instance. The value is fixed as Postpaid. Note For more information about how to change the billing method of the new instance after an upgrade, see Switch the billing method of an ApsaraDB RDS for PostgreSQL instance from pay-as-you-go to subscription.
InstanceNetworkType	String	No	VPC	The network type of the new instance. The value is fixed as VPC. The major engine version upgrade feature is supported only for instances that reside in VPCs. If the original instance resides in the classic network, you must migrate the instance to a VPC before you call this operation. For more information about how to view or change the network type of an instance, see Change the network type of an ApsaraDB RDS for PostgreSQL instance.
SwitchTimeMode	String	No	Immediate	The time at which ApsaraDB RDS switches your workloads over to the new instance. This parameter is used together with the SwitchOver parameter and takes effect only when you set the SwitchOver parameter to true. Valid values: Immediate: After data is migrated to the new instance, ApsaraDB RDS immediately switches your workloads over to the new instance. MaintainTime: After data is migrated to the new instance, ApsaraDB RDS switches your workloads over to the new instance during the maintenance window that you specify. You can call the ModifyDBInstanceMaintainTime operation to change the maintenance window of an instance.
SwitchTime	String	No	2021-07-10T13:15:12Z	A reserved parameter. You do not need to specify this parameter.
SwitchOver	String	No	false	Specifies whether ApsaraDB RDS automatically switches your workloads over to the new instance after data is migrated to the new instance. Valid values: true: ApsaraDB RDS automatically switches workloads over to the new instance. false: ApsaraDB RDS does not automatically switch your workloads over to the new instance. Before you perform an upgrade, we recommend that you set this parameter to false to test whether the new major engine version is compatible with your workloads. Note If you set this parameter to true, you must take note of the following information: After the switchover is complete, you cannot roll your workloads back to the original RDS instance. Proceed with caution. During the switchover, the original instance processes only read requests. We recommend that you perform the switchover during off-peak hours. If read-only instances are attached to the original instance, you can set this parameter only to false. In this case, the read-only instances that are attached to the original instance cannot be cloned. After the upgrade is complete, you must create read-only instances for the new instance. If you set this parameter to false, you must take note of the following information: The data migration does not interrupt your workloads on the original instance. After data is migrated to the new instance, you must update the endpoint configuration on your application. This update requires you to replace the endpoint of the original instance with the endpoint of the new instance. For more information about how to view the endpoint of an instance, see View and change the internal and public endpoints and port numbers of an ApsaraDB RDS for PostgreSQL instance.
CollectStatMode	String	No	After	The time at which ApsaraDB RDS collects the statistics of the new instance. Valid values: Before: ApsaraDB RDS collects the statistics of the new instance before the switchover to ensure service stability. If the original instance contains a large amount of data, the upgrade may require a long period of time. After: ApsaraDB RDS collects the statistics of the new instance after the switchover to accelerate the upgrade. If you access tables for which no statistics are generated, the execution plans that you specify may be inaccurate. In addition, your database service may be unavailable during peak hours. Note If you set the SwitchOver parameter to false, the value Before specifies that ApsaraDB RDS collects the statistics of the new instance before the new instance starts to process read and write requests, and the value After specifies that ApsaraDB RDS collects the statistics of the new instance after the new instance starts to process read and write requests.
TargetMajorVersion	String	No	13.0	The major engine version of the new instance. The value of this parameter must be the major engine version on which an upgrade check is performed. Note You can call the UpgradeDBInstanceMajorVersionPrecheck operation to perform an upgrade check on a major engine version.
DBInstanceId	String	No	pgm-bp1gm3yh0ht1****	The ID of the original instance.
VPCId	String	No	vpc-bp1opxu1zkhn00gzv****	The ID of the VPC in which the original instance resides. You can call the DescribeDBInstanceAttribute operation to query the VPC ID of the instance.
VSwitchId	String	No	vsw-bp10aqj6o4lclxdrm**,vsw-bp10aqj6o4lclxdrm**	If the original instance runs RDS Basic Edition, you must enter the vSwitch ID of the new instance. If the original instance runs RDS High-availability Edition, you must enter the vSwitch ID of the new instance and the vSwitch ID of the secondary instance of the new instance. Make sure that you separate the vSwitch IDs with commas (,). Note The vSwitches that you specify must reside in the same zone as the original instance. You can call the DescribeVSwitches operation to query vSwitch IDs.
PrivateIpAddress	String	No	172.16.XX.XX	The internal IP address of the new instance. You do not need to specify this parameter. ApsaraDB RDS automatically assigns an internal IP address based on the values of the VPCId and vSwitchId parameters.
UsedTime	String	No	1	A reserved parameter. You do not need to specify this parameter.
Period	String	No	Month	A reserved parameter. You do not need to specify this parameter.
DBInstanceStorageType	String	No	cloud_essd	The storage type of the new instance. Valid values: cloud_ssd: standard SSD cloud_essd: ESSD of PL1 cloud_essd2: ESSD of PL2 cloud_essd3: ESSD of PL3 The major engine version upgrade feature is based on SSD snapshots. You can select a storage type based on the following conditions: If the original instance uses standard SSDs, you can set this parameter to cloud_ssd. If the original instance uses ESSDs, you can set this parameter to cloud_essd, cloud_essd2, or cloud_essd3. If the original instance uses local SSDs, you can set this parameter to cloud_essd, cloud_essd2, or cloud_essd3.
ZoneId	String	No	cn-hangzhou-h	The zone ID of the new instance. You can call the DescribeRegions operation to query the zone ID. You can select a zone that belongs to the region in which the original instance resides. The zone can be different from the zone of the original instance.
ZoneIdSlave1	String	No	cn-hangzhou-h	The zone ID of the secondary instance for the new instance. You can specify this parameter only when the original instance runs RDS High-availability Edition. You can select a zone that belongs to the region in which the original instance resides. The zone can be different from the zone of the original instance. You can call the DescribeRegions operation to query the zone ID.
ZoneIdSlave2	String	No	cn-hangzhou-h	A reserved parameter. You do not need to specify this parameter.

Response parameters


Parameter	Type	Example	Description
DBInstanceId	String	pgm-bp1gm3yh0ht1****	The ID of the instance.
RequestId	String	006729E5-2A33-5955-89E3-651D3F44EBE6	The ID of the request.
OrderId	String	21128667463****	The ID of the order.
TaskId	Long	416980000	A reserved parameter.

Examples

Sample requests

http(s)://rds.aliyuncs.com/?Action=UpgradeDBInstanceMajorVersion
&PayType=Postpaid
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<UpgradeDBInstanceMajorVersion>
    <RequestId>006729E5-2A33-5955-89E3-651D3F44EBE6</RequestId>
    <DBInstanceId>pgm-bp1gm3yh0ht1****</DBInstanceId>
    <OrderId>21128667463****</OrderId>
</UpgradeDBInstanceMajorVersion>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "006729E5-2A33-5955-89E3-651D3F44EBE6",
  "DBInstanceId" : "pgm-bp1gm3yh0ht1****",
  "OrderId" : "21128667463****"
}

Error codes


HTTP status code	Error code	Error message	Description
400	InvalidUpgradePrecheckResult	The upgrade precheck failed. No successful precheck task found in the past 7 days	The error message returned because the upgrade check failed and no upgrade checks are successful over the most recent seven days.
400	TargetEngineVersion.Parameters.NotFound	targetEngineVersion is missing in the request.	The error message returned because the TargetMajorVersion parameter is not specified.
400	InvalidDBInstanceStorageType	The specified DBInstanceStorageType is invalid.	The error message returned because the value of the DBInstanceStorageType parameter is invalid.
400	InvalidInstanceNetworkType	The specified InstanceNetworkType is invalid.	The error message returned because the value of the InstanceNetworkType parameter is invalid.
400	InvalidVPCId	The specified VPCId is invalid.	The error message returned because the value of the VPCId parameter is invalid.
400	InvalidDedicatedHostGroupId	The specified DedicatedHostGroupId is invalid.	The error message returned because an invalid dedicated cluster ID is specified.
400	InvalidPayType	The specified PayType is invalid.	The error message returned because the value of the PayType parameter is invalid.
400	InvalidEngineVersion	The specified EngineVersion is invalid.	The error message returned because the value of the TargetMajorVersion parameter is invalid.
400	InvalidDBInstanceStorage	The specified DBInstanceStorage is invalid.	The error message returned because the value of the DBInstanceStorage parameter is invalid.
400	InvalidSwitchOver	The specified SwitchOver is invalid.	The error message returned because the value of the SwitchOver parameter is invalid.
400	PrimaryInstanceWithReadonlyNotSupport	The specified primary instance with the read-only instance does not support the operation.	The error message returned because read-only instances are attached to the original instance. This operation is not supported for instances to which read-only instances are attached.
400	InvalidSwitchTimeMode	The specified SwitchTimeMode is invalid.	The error message returned because the value of the SwitchTimeMode parameter is invalid.
400	InvalidSwitchTime	The specified SwitchTime is invalid.	The error message returned because the value of the SwitchTime parameter is invalid.
400	InvalidCollectStats	The specified CollectStats is invalid.	The error message returned because the value of the CollectStatMode parameter is invalid.
400	IncorrectDBInstanceState	The current instance state does not support this operation.	The error message returned because this operation is not supported for the state in which the instance stays.
400	InvalidDBinstanceClass.ValueNotSupported	The specified parameter DBinstanceClass is invalid.	The error message returned because the value of the DBInstanceClass parameter is invalid.
404	InvalidDBInstanceName.NotFound	The database instance does not exist.	The error message returned because the name of the original instance cannot be found. Check whether the name is correct.
404	IncorrectDBInstanceLockMode	Current DB instance lock mode does not support this operation.	The error message returned because the instance is locked.

For a list of error codes, visit the Service error codes.