You can call the ModifyBackupPolicy operation to modify the backup settings of an ApsaraDB RDS instance.

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

  • The instance must not be a read-only instance.
  • The instance must be in the Running state.

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 ModifyBackupPolicy

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

DBInstanceId String Yes rm-uf6wjk5xxxxxxx

The ID of the instance. You can call the DescribeDBInstances operation to query the IDs of instances.

BackupPolicyMode String No DataBackupPolicy

The type of backup that you want to perform. Valid values:

  • DataBackupPolicy: data backup
  • LogBackupPolicy: log backup
PreferredBackupTime String No 00:00Z-01:00Z

The time at which you want to perform a backup. Specify the time in the ISO 8601 standard in the HH:mmZ-HH:mmZ format. The time must be in UTC.

Note
  • You must specify this parameter when you set the BackupPolicyMode parameter to DataBackupPolicy.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
PreferredBackupPeriod String No Monday

The cycle based on which you want to perform a backup. Specify at least two days of the week and separate the days with commas (,). Valid values:

  • Monday
  • Tuesday
  • Wednesday
  • Thursday
  • Friday
  • Saturday
  • Sunday
Note
  • You can configure a backup policy by using this parameter and the BackupInterval parameter. For example, if you set this parameter to Saturday,Sunday and set the BackupInterval parameter to 30 minutes, a backup is performed once every 30 minutes on every Saturday and Sunday.
  • You must specify this parameter when you set the BackupPolicyMode parameter to DataBackupPolicy.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
BackupRetentionPeriod String No 7

The number of days for which you want to retain data backup files. Valid values: 7 to 730.

Note
  • You must specify this parameter when you set the BackupPolicyMode parameter to DataBackupPolicy.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
BackupLog String No Enable

Specifies whether to enable the log backup feature. Valid values:

  • Enable: The log backup feature is enabled.
  • Disabled: The log backup feature is disabled.
Note
  • This parameter specifies whether to enable the log backup feature if you set the BackupPolicyMode parameter to DataBackupPolicy.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
LogBackupRetentionPeriod String No 7

The number of days for which you want to retain log backup files. Valid values: 7 to 730. The log backup retention period cannot be longer than the data backup retention period.

Note
  • If you enable the log backup feature, you can specify the log backup retention period. This parameter is supported only by instances that run MySQL, PostgreSQL, or PPAS.
  • This parameter takes effect no matter whether you set the BackupPolicyMode parameter to DataBackupPolicy or LogBackupPolicy.
EnableBackupLog String No 1

Specifies whether to enable the log backup feature. Valid values:

  • True or 1: The log backup feature is enabled.
  • False or 0: The log backup feature is disabled.
Note
  • This parameter specifies whether to enable the log backup feature if you set the BackupPolicyMode parameter to LogBackupPolicy.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to LogBackupPolicy.
LocalLogRetentionHours String No 18

The number of hours for which you want to retain log backup files on the instance. Valid values: 0 to 7 × 24. The value 0 specifies that log backup files are not retained on the instance.

Note
  • You must specify this parameter if you set the BackupPolicyMode parameter to LogBackupPolicy.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to LogBackupPolicy.
LocalLogRetentionSpace String No 30

The maximum storage usage that is allowed for log backup files on the instance. If the storage usage for log backup files on the instance exceeds the value of this parameter, ApsaraDB RDS deletes earlier log backup files until the storage usage falls below the value of this parameter. Valid values: 0 to 50. If you do not specify this parameter, the existing value of this parameter is retained.

Note
  • You must specify this parameter if you set the BackupPolicyMode parameter to LogBackupPolicy.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to LogBackupPolicy.
HighSpaceUsageProtection String No Enable

Specifies whether ApsaraDB RDS forcibly deletes log backup files from the instance when the storage usage of the instance exceeds 80% or the amount of remaining storage on the instance is less than 5 GB. Valid values: Enable and Disable. If you do not specify this parameter, the existing value of this parameter is retained.

Note
  • You must specify this parameter if you set the BackupPolicyMode parameter to LogBackupPolicy.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to LogBackupPolicy.
LogBackupFrequency String No LogInterval

The frequency at which you want to back up the binary logs of the instance. Valid values:

  • The value LogInterval specifies to back up the binary logs every 30 minutes.
  • The default value of this parameter is the same as the data backup frequency.
Note
  • The value LogInterval is supported only by instances that run SQL Server.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
CompressType String No 4

The format into which backup files are compressed. Valid values:

  • 1: The zlib tool is used to compress backup files into .tar.gz files.
  • 4: The QuickLZ tool is used to compress backup files into .xb.gz files. This compression format is supported only by instances that run MySQL 5.6 or MySQL 5.7. Backup files in this compression format can be used to restore individual databases and tables. For more information, see Restore the individual databases and tables of an ApsaraDB RDS for MySQL instance.
  • 8: The QuickLZ tool is used to compress data into .xb.gz files. This compression format is supported only by instances that run MySQL 8.0. Backup files in this compression format can be used to restore individual databases and tables.
Note This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
ArchiveBackupRetentionPeriod String No 365

The number of days for which you want to retain archived backup files. The default value 0 specifies that the backup archiving feature is not enabled. Valid values: 30 to 1095.

Note This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
ArchiveBackupKeepPolicy String No ByMonth

The unit that is used to measure the period of time for which you want to retain archived backup files. The number of archived backup files that can be retained within the specified retention period is specified by the ArchiveBackupKeepCount parameter. Default value: 0. Valid values:

  • ByMonth
  • ByWeek
  • KeepAll
Note This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
ArchiveBackupKeepCount Integer No 1

The number of archived backup files that you want to retain. Default value: 1. Valid values:

  • The value of this parameter ranges from 1 to 31 if you set the ArchiveBackupKeepPolicy parameter to ByMonth.
  • The value of this parameter ranges from 1 to 7 if you set the ArchiveBackupKeepPolicy parameter to ByWeek.
Note
  • You do not need to specify this parameter if you set the ArchiveBackupKeepPolicy parameter to KeepAll.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
ReleasedKeepPolicy String No None

The policy based on which ApsaraDB RDS retains archived backup files if the instance is released. Default value: None. Valid values:

  • None: No archived backup files are retained.
  • Lastest: Only the most recent archived backup file is retained.
  • All: All archived backup files are retained.
Note This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
LogBackupLocalRetentionNumber Integer No 60

The number of log backup files that you want to retain on the instance. Default value: 60. Valid values: 6 to 100.

Note
  • This parameter takes effect only when you set the BackupPolicyMode parameter to LogBackupPolicy.
  • If the instance runs MySQL, you can set this parameter to -1 to specify that an unlimited number of log backup files can be retained on the instance.
Category String No Standard

Specifies whether to enable the single-digit second backup feature. This feature allows ApsaraDB RDS to complete a backup within a few seconds. Valid values:

  • Flash: The single-digit second backup feature is enabled.
  • Standard: The single-digit second backup feature is disabled.
Note This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
BackupInterval String No 30

The frequency at which you want to perform a snapshot backup. Valid values:

  • -1: No snapshot backup frequency is specified.
  • 30: A snapshot backup is performed once every 30 minutes.
  • 60: A snapshot backup is performed once every 60 minutes.
  • 120: A snapshot backup is performed once every 120 minutes.
  • 240: A snapshot backup is performed once every 240 minutes.
  • 480: A snapshot backup is performed once every 480 minutes.
Note
  • You can configure a backup policy by using this parameter and the PreferredBackupPeriod parameter. For example, if you set the PreferredBackupPeriod parameter to Saturday,Sunday and set the BackupInterval parameter to -1, a snapshot backup is performed on every Saturday and Sunday.
  • If the instance runs PostgreSQL, the BackupInterval parameter is supported only when the instance is equipped with standard SSDs or enhanced SSDs (ESSDs).
  • If the instance runs SQL Server, the BackupInterval parameter is supported only when the snapshot backup feature is enabled for the instance. For more information, see Enable snapshot backups for an ApsaraDB RDS for SQL Server instance.
  • This parameter is invalid if you set the Category parameter to Flash.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.
BackupMethod String No Physical

The backup method of the instance. Valid values:

  • Physical: physical backup
  • Snapshot: snapshot backup

Default value: Physical.

Note
  • This parameter takes effect only on instances that run SQL Server with standard SSDs or ESSDs.
  • This parameter takes effect only when you set the BackupPolicyMode parameter to DataBackupPolicy.

Response parameters

Parameter Type Example Description
CompressType String 4

The format into which backup files are compressed. Valid values:

  • 0: Backup files are not compressed.
  • 1: Backup files are compressed by using the zlib tool.
  • 2: Backup files are compressed in parallel by using the zlib tool.
  • 4: Backup files are compressed by using the QuickLZ tool and can be used to restore individual databases and tables.
  • 8: Backup files are compressed by using the QuickLZ tool but cannot be used to restore individual databases or tables. This value is supported only by instances that run MySQL 8.0.
DBInstanceID String rm-uf6wjk5xxxxxxx

The ID of the instance.

EnableBackupLog String 1

Indicates whether the log backup feature is enabled. Valid values:

  • 1: The log backup feature is enabled.
  • 0: The log backup feature is disabled
HighSpaceUsageProtection String Disable

Indicates whether ApsaraDB RDS forcibly deletes log backup files from the instance when the storage usage of the instance exceeds 80% or the amount of remaining storage on the instance is less than 5 GB.

LocalLogRetentionHours Integer 18

The number of hours for which log backup files are retained on the instance.

LocalLogRetentionSpace String 30

The maximum storage usage that is allowed for log backup files on the instance.

LogBackupLocalRetentionNumber Integer 60

The number of log backup files that can be retained on the instance.

RequestId String DA147739-AEAD-4417-9089-65E9B1D8240D

The ID of the request.

Examples

Sample requests

http(s)://rds.aliyuncs.com/?Action=ModifyBackupPolicy
&DBInstanceId=rm-uf6wjk5xxxxxxx
&<Common request parameters>

Sample success responses

XML format

<ModifyBackupPolicyResponse>
        <HighSpaceUsageProtection>Disable</HighSpaceUsageProtection>
      <DBInstanceID>rm-bp1z3xxxxx</DBInstanceID>
      <RequestId>E4BF5598-ED12-4406-AAA4-F375428BE741</RequestId>
      <LocalLogRetentionHours>18</LocalLogRetentionHours>
      <EnableBackupLog>1</EnableBackupLog>
      <LocalLogRetentionSpace>30</LocalLogRetentionSpace>
      <LogBackupLocalRetentionNumber>60</LogBackupLocalRetentionNumber>
</ModifyBackupPolicyResponse>

JSON format

{
    "HighSpaceUsageProtection": "Disable",
    "DBInstanceID": "rm-bp1z3xxxxx",
    "RequestId": "E4BF5598-ED12-4406-AAA4-F375428BE741",
    "LocalLogRetentionHours": "18",
    "EnableBackupLog": "1",
    "LocalLogRetentionSpace": "30",
    "LogBackupLocalRetentionNumber": 60
}

Error codes

HTTP status code Error code Error message Description
400 InvalidLogBackupFrequency.Malformed Invalid log backup frequency. The error message returned because the value of the LogBackupFrequency parameter is invalid.
400 InvalidBackupRetentionPeriod.Malformed The specified backup retention period is invalid. The error message returned because no backup retention period is specified. Specify a backup retention period. The backup retention period cannot be shorter than 1 day or longer than 30 days.
400 BackupPropertyNotFound Backup policy not found The error message returned because no backup policy can be found.
400 OperationDenied.SwitchToSnapshot Snapshot backup does not support cross region storage at present. Please turn off cross region backup before switching to snapshot backup mode. The error message returned because snapshot backup files cannot be stored to a region that is different from the region where the instance resides. Before you enable the snapshot backup feature, you must disable the cross-region backup feature.
403 OperationDenied.SwitchSnapshotToPhysical Only physical backup to snapshot backup is supported. The error message returned because the operation supports only the change from the physical backup method to the snapshot backup method.
403 OperationDenied.ModifyBackupSwitchOff The switch is not turned on. It is forbidden to modify the backup mode. The error message returned because the cross-region backup feature is not enabled.
403 OperationDenied.ApiForbiddenForLogBackupFrequency When the instance is a snapshot backup, the log backup frequency is not allowed to be consistent with the data backup. The error message returned because the log backup frequency cannot be the same as the data backup frequency when the snapshot backup feature is enabled.
403 OperationDenied.NotSupportedBackupMethod When the storage is larger than 4000 GB, only snapshot backup is supported. The error message returned because the instance supports only snapshot backups when the remaining storage is greater than 4,000 GB.
403 OperationDenied.ApiForbidden Operation is not permitted. The error message returned because the operation is not allowed.

For a list of error codes, visit the API Error Center.