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

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 new 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.

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 must run PostgreSQL 12, PostgreSQL 11, PostgreSQL 10, or PostgreSQL 9.4.
  • The original instance must run RDS High-availability Edition or RDS Basic Edition.
  • The original instance must reside in a virtual private cloud (VPC). If the original instance resides in the classic network, you must migrate the original 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.
  • The ID of the original instance cannot start with pg-cn.

An upgrade brings 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 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.

Request parameters

Parameter Type Required Example Description
Action String No 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

The storage capacity of the new instance must be greater than or equal to the storage capacity of the original instance and cannot exceed 3,200 GB.

PayType String Yes Postpaid

The billing method of the new instance. Set the value to 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. Set the value to VPC. The major 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 original 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

This parameter is reserved. 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 instance. Proceed with caution.
    • During the switchover, the original instance processes only read requests. You must 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:
CollectStatMode String No After

The time at which ApsaraDB RDS collects the statistics of the new instance.

  • 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 query plans that you specify may be inaccurately executed. 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 IDs of instances.

VSwitchId String No vsw-bp10aqj6o4lclxdrm****,vsw-bp10aqj6o4lclxdrm****
  • If the original instance runs RDS Basic Edition, enter the vSwitch ID of the new instance.
  • If the original instance runs RDS High-availability Edition, 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

This parameter is reserved. You do not need to specify this parameter.

Period String No Month

This parameter is reserved. 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: enhanced SSDs (ESSDs) of performance level 1 (PL1)
  • cloud_essd2: ESSDs of PL2
  • cloud_essd3: ESSDs of PL3

The major 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 select standard SSDs.
  • If the original instance uses ESSDs, you can select ESSDs of PL1, ESSDs of PL2, or ESSDs of PL3.
  • If the original instance uses local SSDs, you can select ESSDs of PL1, ESSDs of PL2, or ESSDs of PL3.
ZoneId String No cn-hangzhou-h

The ID of the zone to which the new instance belongs. You can call the DescribeRegions operation to query zone IDs.

You can select a zone that belongs to the region where the original instance resides.

ZoneIdSlave1 String No cn-hangzhou-h

The ID of the zone to which the secondary instance of the new instance belongs. 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 where the original instance resides.

You can call the DescribeRegions operation to query zone IDs.

ZoneIdSlave2 String No cn-hangzhou-h

This parameter is reserved. You do not need to specify this parameter.

Response parameters

Parameter Type Example Description
DBInstanceId String pgm-bp1gm3yh0ht1****

The ID of the original instance.

RequestId String 006729E5-2A33-5955-89E3-651D3F44EBE6

The ID of the request.

OrderId String 21128667463****

The ID of the order.

TaskId Long 416980000

This parameter is reserved.

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 API Error Center.