You can call the ModifyDBInstanceSpec operation to change the instance type or storage capacity of an instance. This operation is supported for primary instances and read-only instances. This operation is not supported for disaster recovery instances or temporary instances.

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

  • The instance is in the Running state.
  • The instance has no ongoing backup tasks.
  • At least one of the DBInstanceClass and DBInstanceStorage parameters is specified in the request.
  • If you want to decrease the storage capacity, the new storage capacity that you specify must be greater than or equal to 1.1 times the used storage capacity.
  • The instance is a primary or read-only instance.
Note If you want to upgrade the RDS edition of the instance, you need to only select an instance type that supports the new RDS edition. For example, if you want to upgrade the RDS edition of the instance from RDS Basic Edition to RDS High-availability Edition, you need to only select an instance type that supports RDS High-availability Edition.

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 Yes ModifyDBInstanceSpec

The operation that you want to perform. Set the value to ModifyDBInstanceSpec.

DBInstanceId String Yes rm-uf6wjk5*******

The ID of the instance.

DBInstanceClass String No rds.mys2.small

The new instance type of the instance. For more information, see Primary ApsaraDB RDS instance types. You can call the DescribeAvailableClasses operation to query the instance types that are available in a region.

Note
  • You must specify at least one of the DBInstanceClass and DBInstanceStorage parameters.
  • You can call the DescribeDBInstanceAttribute operation to query the in-use instance type of the instance.
DBInstanceStorage Integer No 20

The new storage capacity of the instance. Unit: GB. You can increase the storage capacity at a step size of 5 GB. For more information, see Primary ApsaraDB RDS instance types. You can call the DescribeAvailableClasses operation to query the storage capacity range that is supported by an instance type.

Note
  • You must specify at least one of the DBInstanceStorage and DBInstanceClass parameters.
  • If the instance runs MySQL on RDS High-availability Edition and uses local SSDs, you can decrease the storage capacity at a step size of 5 GB.
  • You can call the DescribeDBInstanceAttribute operation to query the current storage capacity of the instance.
PayType String Yes Postpaid

The billing method of the instance. Valid values:

  • Postpaid: pay-as-you-go
  • Prepaid: subscription
EffectiveTime String No MaintainTime

The time when you want the change to take effect. Valid values:

  • Immediate: The change immediately takes effect.
  • MaintainTime: The change takes effect during the specified maintenance window. For more information, see ModifyDBInstanceMaintainTime.
Note Default value: Immediate.
EngineVersion String No 5.6

The database engine version of the instance.

  • Valid values when you set the Engine parameter to MySQL: 5.5, 5.6, 5.7, and 8.0
  • Valid values when you set the Engine parameter to SQLServer: 2008r2, 08r2_ent_ha, 2012, 2012_ent_ha, 2012_std_ha, 2012_web, 2014_std_ha, 2016_ent_ha, 2016_std_ha, 2016_web, 2017_std_ha, 2017_ent, 2019_std_ha, and 2019_ent
  • Valid values when you set the Engine parameter to PostgreSQL: 10.0, 11.0, 12.0, 13.0, 14.0, and 15.0
  • Valid values when you set the Engine parameter to MariaDB: 10.3
DBInstanceStorageType String No local_ssd

The storage type of the instance. Valid values:

  • local_ssd: local SSD.
  • cloud_ssd: standard SSD. This storage type is not recommended and is unavailable in some Alibaba Cloud regions.
  • cloud_essd: enhanced SSD (ESSD) of performance level 1 (PL1).
  • cloud_essd2: ESSD of PL2.
  • cloud_essd3: ESSD of PL3.

To change the storage type, take note of the following items:

  • If the instance runs PostgreSQL, you can upgrade the storage type of the instance from standard SSD to ESSD. However, you cannot downgrade the storage type of the instance from ESSD to standard SSD. ESSDs provide the following performance levels (PLs): ESSDs of PL1, ESSDs of PL2, and ESSDs of PL3. You can upgrade or downgrade the storage type between ESSD of PL1, ESSD of PL2, and ESSD of PL3. For more information, see Configuration items.
Direction String No Up

The type of the change that you want to perform on the instance. Valid values:

  • Up: upgrades a subscription instance, or upgrades or downgrades a pay-as-you-go instance.
  • Down: downgrades a subscription instance.
  • TempUpgrade: performs elastic specification changes on a subscription instance. This value is required for elastic specification changes.
Note
  • Default value: Up.
  • If you specify only the DBInstanceStorageType parameter, you can leave the Direction parameter empty. For example, if you want only to change the storage type of the instance from standard SSD to ESSD, you do not need to specify the Direction parameter.
SourceBiz String No N/A

A deprecated parameter.

DedicatedHostGroupId String No dhg-7a9********

The ID of the dedicated cluster to which the instance belongs.

ZoneId String No cn-hangzhou-b

The zone ID of the instance.

SwitchTime String No 2019-07-10T13:15:12Z

The time at which you want to change the specifications. We recommend that you change the specifications during off-peak hours. Specify the time in the ISO 8601 standard in the yyyy-MM-ddTHH:mm:ssZ format. The time must be in UTC.

Note
  • You must specify a point in time later than the current time. Otherwise, the specification change task fails. The current time refers to the time to call this operation. If the specification change task fails, you must wait for the order to be automatically canceled, and then call this operation again.
  • If you want to increase the storage capacity or change the ESSD storage type between different PLs, the specification change immediately takes effect and does not affect your workloads. You do not need to configure this parameter.
ResourceGroupId String No rg-acfmy**********

The ID of the resource group to which the instance belongs.

UsedTime Long No 3

The validity period of the specification changes on an ApsaraDB RDS for SQL Server instance. Unit: days.

MaxCapacity double No 8

The maximum number of RDS Capacity Units (RCUs).

MinCapacity double No 0.5

The minimum number of RCUs.

AutoPause Boolean No true

Specifies whether to support automatic suspension.

SwitchForce Boolean No false

Specifies whether to enable the forced scaling feature for the serverless instance. Valid values:

  • true: enables the feature.
  • false: disables the feature. This is the default value.
Category String No HighAvailability

The RDS edition of the instance. Valid values:

  • Basic: RDS Basic Edition.
  • HighAvailability: RDS High-availability Edition.

  • AlwaysOn: RDS Cluster Edition for SQL Server

  • Finance: RDS Enterprise Edition. This edition is available only on the China site (aliyun.com).
Note If you set the EngineVersion parameter to an SQL Server version, you must also specify this parameter.

Response parameters

Parameter Type Example Description
DBInstanceId String rm-uf6wjk5*******

The ID of the instance.

RequestId String 3C5CFDEE-F774-4DED-89A2-1D76EC63C575

The ID of the request.

OrderId Long 20793850608****

The ID of the order.

Examples

Sample requests

http(s)://rds.aliyuncs.com/?Action=ModifyDBInstanceSpec
&DBInstanceId=rm-uf6wjk5*******
&PayType=Postpaid
&DBInstanceClass=rds.mys2.small
&<Common request parameters>

Sample success responses

XML format

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

<ModifyDBInstanceSpecResponse>
    <RequestId>3C5CFDEE-F774-4DED-89A2-1D76EC63C575</RequestId>
    <DBInstanceId>rm-uf6wjk5*******</DBInstanceId>
    <OrderId>20793850608****</OrderId>
</ModifyDBInstanceSpecResponse>

JSON format

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

{
  "RequestId" : "3C5CFDEE-F774-4DED-89A2-1D76EC63C575",
  "DBInstanceId" : "rm-uf6wjk5*******",
  "OrderId" : "20793850608****"
}

Error codes

Http status code Error code Error message Description
400 CannotDecreaseEssdPerfLevel cannot decrease cloud essd performance level. The error message returned because the change of the storage type is not allowed. The storage type of an instance that runs SQL Server with standard SSDs can be changed only to ESSDs. The storage type of an instance that runs SQL Server with local SSDs can be changed to standard SSDs or ESSDs.
400 InvalidEssdStorageSize invalid cloud essd storage size. The error message returned because the specified instance type is invalid. You must select a valid instance type and try again.
400 NotSupportReduceDiskSize Not support reduce disk size. The error message returned because the storage capacity of the instance cannot be decreased.
400 InvalidDBInstanceClass.NotFound Specified DB instance class is not found. The error message returned because the new instance type cannot be found or is no longer available for purchase. You must select an available instance type.
400 InvalidAvZone.Format Specified AvZone is not valid. The error message returned because the value of the ZoneID parameter is invalid.
400 OperationDenied.OrderUnPaid The operation is not permitted due to the wrong Order status (Unpaid). The error message returned because you have unpaid orders. You must pay for the orders before you call this operation.
400 OperationDenied.InvalidStorageSize The storage size limit is exceeded. The error message returned because the storage usage exceeds the upper limit. You must clear or expand the storage capacity.
400 InsufficientResourceCapacity The instance cluster does not support this operation. The error message returned because the operation is not supported in the dedicated cluster to which the instance belongs.
400 InvalidUsedTime The parameter usedTime is invalid. The error message returned because the value of the UsedTime parameter is invalid.
400 CannotChangeStorageType Temp upgrade does not support changing storage type. The error message returned because elastic upgrades do not support storage type changes.
400 TempUpgrade.NotSupport The instance does not support temp upgrade. The error message returned because the instance does not support elastic upgrades.
400 EngineNotSupported Engine specified cannot be supported the operation. The error message returned because this operation is not supported for the database engine that is run on the instance. You must update the minor engine version.
400 MaxscaleNotSupport Maxscale not supported The error message returned because the instance does not support the database proxy feature. Check the database proxy configuration that you specified.
400 ADInstanceNotSupportThisOperation The AD instance is not supported this operation The error message returned because the operation is not supported for an instance that is added to an Active Directory (AD) domain.
400 BYOKInstanceNotSupportThisOperation The BYOK instance is not supported this operation The error message returned because the operation is not supported for an instance for which disk encryption is enabled.
400 BYOLInstanceNotSupportThisOperation The BYOL instance is not supported this operation The error message returned because the operation is not supported for an instance that uses Bring Your Own License (BYOL).
400 SSLInstanceNotSupportThisOperation The instance opened SSL, upgrade is not this operation The error message returned because the operation is not supported for an instance for which the SSL encryption feature is enabled.
400 TDEInstanceNotSupportThisOperation The instance opened TDE, this operation is not supported The error message returned because the operation is not supported for an instance for which the Transparent Data Encryption (TDE) feature is enabled.
400 InstanceIsSnapshotBackupNotSupportThisOperation The instance backup method is snapshot backup, this operation is not supported The error message returned because the operation is not supported for an instance for which the snapshot backup feature is enabled.
400 InstanceHasReadOnlyInstanceNotSupportThisOperation The instance has read-only instance or is read-only instance, this operation is not supported The error message returned because the operation is not supported for a read-only instance or an instance to which read-only instances are attached.
400 BackupReadInstanceModifyNotAllowed Modify Backup Read Instance Is Not Allowed. The error message returned because you are not allowed to modify the instance from which the backup comes.
400 MinorVersionNotSupport The current database minor version does not support the operation. The error message returned because the operation is not supported by the current minor engine version of the instance.
400 LX.ARGUMENT.ILLEGAL The parameters that you specified for the specification change are invalid. The error message returned because the parameters that you specified for the specification change are invalid.
400 ORD.S.QUERY.PROD.ERROR An error occurred while querying the ordering information The error message returned because the order cannot be found.
403 IncorrectDBInstanceType The database instance type does not support the operation. The error message returned because the operation is not supported by the database engine that is run on the instance.
403 OperationDenied.NotSupportedBackupMethod When the storage is larger than 4000 GB, only snapshot backup is supported. The error message returned because the storage capacity is greater than 4,000 GB and only snapshot backups are supported.
403 IncorrectReadDBInstanceDisksize Read instance disk size must be equal or higher than primary instance. The error message returned because the storage capacity of the read-only instance is less than the storage capacity of the primary instance. Make sure that the storage capacity of the read-only instance is greater than or equal to the storage capacity of the primary instance.
403 GroupReplicationNotSupport.InvalidEngineVersion Group Replication requires the instance engine version to be 8.0. The error message returned because the major engine version of the instance is not MySQL 8.0 and MySQL group replication (MGR) is not supported.
403 GroupReplicationNotSupport.InvalidNodeClassCode Group Replication requires the ClassCode of each node to be consistent. The error message returned because the specifications of the nodes in the instance are different and MGR is not supported.
403 GroupReplicationNotSupport.InvalidNodeNum Group Replication is not supported, the number of nodes must be an odd number greater than or equal to 3. The error message returned because the number of nodes in the instance is not an odd number greater than or equal to 3 and MGR is not supported.
403 GroupReplicationNotSupport.InvalidXengine Group Replication is not supported because the instance has xengine tables. The error message returned because X-Engine tables exist in the instance and MGR is not supported.
403 GroupReplicationNotSupport.MemoryTooSmall Group Replication is not supported because the memory is too small. The error message returned because the memory capacity of the instance is small and MGR is not supported.
403 ARMNotSupport ARM arch does not support this operation. The error message returned because this operation is not supported by the ARM architecture.
403 HostTypeNotSupport Host type is inconsistent, please check that the original host type is the same as the target host type. The error message returned because the host types before and after the specification change are different.
403 CloudSSDNotSupport Cloud ssd does not support this operation, please upgrade to essd. The error message returned because the operation is not supported by the standard SSD storage type. You must upgrade storage type of the instance to ESSD.
403 MaxscaleInstanceNotSupport Instances with maxscale instance do not support this operation. The error message returned because the operation is not supported by the instance for which MaxScale is enabled.
403 ReadInstanceNotSupport Instances with read-only do not support this operation. The error message returned because the operation is not supported by the instance to which read-only instances are attached.
404 InvalidClusterKms The current instance does not authorized to access the Key Management Service. The error message returned because the instance does not have permissions to access Key Management Service (KMS).

For a list of error codes, see Service error codes.