Menu
Amazon Relational Database Service
Command Line Interface Reference (API Version 2014-10-31)

rds-modify-db-instance

The Amazon RDS Command Line Interface (CLI) has been deprecated. Instead, use the AWS CLI for RDS.

For information on how to download and use the AWS CLI, go to AWS Command Line Interface User Guide. For a reference of the RDS commands available in the AWS CLI, go to AWS CLI Reference for Amazon RDS.

Note

The AWS CLI does not currently support the DownloadCompleteDBLogFile REST API. If you need to download an entire log file at once, rather than in portions using the download-db-log-file-portion command, then you can continue to use the last published version of the RDS CLI and the rds-download-db-logfile command.

Description

Changes the settings of an existing DB instance.

Syntax

rds-modify-db-instance db-instance-identifier

[--allow-major-version-upgrade value ]

[-au (--auto-minor-version-upgrade) value ]

[-v (--engine-version) value ]

[-s (--allocated-storage) value ]

[--apply-immediately ]

[-r (--backup-retention-period) value ]

[-c (--db-instance-class) value ]

[-ct (--copy-tags-to-snapshot) value ]

[--port value ]

[-pub (--publicly-accessible) value ]

[-g (--db-parameter-group-name) value ]

[-a (--db-security-groups)value[,value...] ]

[-sg (--vpc-security-group-ids)value[,value...] ]

[-n (--new-db-instance-identifier) value ]

[-st (--storage-type) value ]

[--iops value ]

[-og (--option-group) value ]

[-p (--master-user-password) value ]

[-m (--multi-az) value]

[-w (--preferred-maintenance-window) value ]

[-b (--preferred-backup-window) value ]

[-tca (--tde-credential-arn) value ]

[-tcp (--tde-credential-password) value ]

[ -cert (--certificate-identifier) value ]

[General Options]

Options

NameDescriptionRequired

--db-instance-identifier value

-D value

DB instance identifier. This is the unique key that identifies an DB instance. Stored as a lowercase string.

This parameter is the default parameter and can be passed as the first value in the command and without a parameter name, for example: rds-modify-db-instance my-db-instance-identifier.

Type: String

Default: None

Constraints: Must contain 1 to 63 (1 to 15 for SQL Server) alphanumeric characters or hyphens. First character must be a letter. Cannot end with a hyphen or contain two consecutive hyphens.

Example: myinstance

Yes

--allow-major-version-upgrade value

Indicates that major version upgrades are allowed. Changing this parameter does not result in an outage and the change is asynchronously applied as soon as possible.

Type: Boolean

Constraints: This parameter must be set to true when specifying a value for the --engine-version parameter that is a different major version than the DB instance's current version.

Conditional

-au value

--auto-minor-version-upgrade value

Indicates that minor version upgrades will be applied automatically to the DB instance during the maintenance window. Changing this parameter does not result in an outage except in the following case and the change is asynchronously applied as soon as possible. An outage will result if this parameter is set to true during the maintenance window, and a newer minor version is available, and RDS has enabled auto patching for that engine version.

Type: Boolean

Example: --au true

No

-n value

--new-db-instance-identifier value

Provides the new name for the DB instance when renaming an existing instance. When you change the DB instance identifier, an instance reboot will occur immediately if you set apply-immediately  to true, or will occur during the next maintenance window if you set apply-immediately to false. This value is stored as a lowercase string.

Type: String

Constraints: Must contain 1 to 63 (1 to 15 for SQL Server) alphanumeric characters or hyphens. First character must be a letter. Cannot end with a hyphen or contain two consecutive hyphens. Cannot be the name of an existing DB instance.

Example: rds-modify-db-instance myDBInstanceIdentifier -n myNewDBInstanceIdentifier

No

-v value

--engine-version value

Version number of the database engine to use. Changing this parameter results in an outage and the change is applied during the next maintenance window unless the apply-immediately parameter is set to true for this request.

Note

For major version upgrades, if a non-default DBParameterGroup is currently in use, a new DBParameterGroup in the DBParameterGroupFamily for the new engine version must be specified. The new DBParameterGroup can be the default for that DBParameterGroupFamily.

Type: String

Valid values: For a list of valid values, see the --engine-version parameter in the rds-create-db-instance

Example: --engine-version 5.1.42

No

--apply-immediately

Determines when a change is applied. If set to True, the change will be applied immediately if possible.

If this parameter is set to False, changes to the DB instance are applied during the next maintenance window. Some parameter changes can cause an outage and will be applied on the next call to rds-reboot-db-instance, or the next failure reboot. Review the table of parameters in Modifying a DB Instance and Using the Apply Immediately Parameter to see the impact that setting --apply-immediately to True or False has for each modified parameter and to determine when the changes will be applied.

Type: Boolean

Default: False

Valid values: True | False

No

-r value

--backup-retention-period value

The number of days for which automated backups are retained. Setting this parameter to a positive number enables backups. Setting this options to 0 disables automatic backups.

Changing this parameter can result in an outage if you change from 0 to a non-zero value or from a non-zero value to 0. These changes are applied during the next maintenance window unless the ApplyImmediately parameter is set to true for this request. If you change the parameter from one non-zero value to another non-zero value, the change is asynchronously applied as soon as possible.

Type: Integer

Default: 1

Constraints:

  • Must be a value from 0 to 35.

  • Can be specified for a DB instance that is a Read Replica only if the source is running MySQL 5.6, or PostgreSQL 9.3.5, 9.3.6, or 9.4.1.

  • Cannot be set to 0 if the DB instance is a source to Read Replicas.

No

-c value

--db-instance-class value

Contains the compute and memory capacity of the DB instance. Different instance classes are available for different database engines. For information about valid values for a particular engine, use the rds-describe-orderable-db-instance-options command.

Changing this parameter results in an outage and the change is applied during the next maintenance window, unless the ApplyImmediately parameter is specified as true for this request.

Type: String

Default: None

Valid values: db.t1.micro | db.m1.small | db.m1.medium | db.m1.large | db.m1.xlarge | db.m2.xlarge | db.m2.2xlarge | db.m2.4xlarge | db.m3.medium | db.m3.large | db.m3.xlarge | db.m3.2xlarge | db.r3.large | db.r3.xlarge | db.r3.2xlarge | db.r3.4xlarge | db.r3.8xlarge | db.t2.micro | db.t2.small | db.t2.medium | db.t2.large | db.m4.large | db.m4.xlarge | db.m4.2xlarge | db.m4.4xlarge | db.m4.10xlarge

Example: --db-instance-class db.m1.xlarge

Example: --db-instance-class db.m1.xlarge

Note

Amazon RDS does not support db.t1.micro instances in a virtual private cloud (VPC).

No

--copy-tags-to-snapshot

-ct

True to copy all tags from the DB instance to snapshots of the DB instance; otherwise false. The default is false.

No

-g value

--db-parameter-group-name value

Name of the DB parameter group to associate with this DB instance.  Changing this setting does not result in an outage. The parameter group name itself is changed immediately, but the actual parameter changes are not applied until you reboot the instance without failover. The DB instance will NOT be rebooted automatically and the parameter changes will NOT be applied during the next maintenance window.

Type: String

Example: --db-parameter-group-name MyDBParameterGroup

No

-a value [,value...]

--db-security-groups value [,value...]

A list of one or more DB security groups to associate with this DB instance. Changing this parameter does not result in an outage and the change is asynchronously applied as soon as possible.

Type: String[]

Example: --db-security-groups mysecuritygroup1, mysecuritygroup2

No

-sg value

--vpc-security-group-ids value [,value...]

A list of the IDs of one or more VPC security groups to associate with this DB instance.

Type: String[]

Example: --vpc-security-group-ids sg-e763f78e, sg-e0690405

No

-p value

--master-user-password value

Password for the master database user. Changing this parameter does not result in an outage and the change is asynchronously applied as soon as possible.

Note

Amazon RDS CLI commands never return the password, so this action provides a way to regain access to a master instance user if the password is lost. This includes restoring privileges that may have been accidentally revoked.

Type: String

MySQL

Constraints: Must contain from 8 to 41 alphanumeric characters.

Type: String

Oracle

Constraints: Must contain from 8 to 30 alphanumeric characters.

Type: String

SQL Server

Constraints: Must contain from 8 to 128 alphanumeric characters.

PostgreSQL

Constraints: Must contain from 8 to 128 alphanumeric characters.

Example: --master-user-password mysecretpassword01

No

-st value

--storage-type value

Specifies the storage type for the DB instance.

Type: String

Valid values: standard | gp2 | io1.

Default: io1 if the --iops parameter is specified; otherwise standard

If you specify io1, you must also include a value for the --iops parameter.

No

--iops value

Specifies the new amount of provisioned IOPS for the DB instance, expressed in I/O operations per second. Changing this parameter does not result in an outage and the change is applied during the next maintenance window unless the --apply-immediately parameter is set to true for this request.

This option can only be specified if the database instance was created with iops specified. The iops and allocated-storage options cannot both be specified in the same request. To set or remove the iops option, or to change the iops-to-storage ratio, create a new database instance and then restore a database instance from a snapshot or to a point-in-time restore.

Constraints: Must be an integer greater than 1000. The value must also be a multiple of the storage amount for the DB instance and can be from 3-10 times the storage amount. For example, if the size of your DB instance is 500GB, then your --iops value can be 2000, 3000, 4000, or 5000.

You can set the --iops value to 0 to disable provisioned IOPS for a DB instance.

Example: rds-modify-db-instance exampledb --region us-west-2 --iops 0 --s 100 --apply-immediately

If you choose to migrate your DB instance from using standard storage to using Provisioned IOPS, or from using Provisioned IOPS to using standard storage, the process can take time. The duration of the migration depends on several factors such as database load, storage size, storage type (standard or Provisioned IOPS), amount of IOPS provisioned (if any), and the number of prior scale storage operations. Typical migration times are under 24 hours, but the process can take up to several days in some cases. During the migration, the DB instance will be available for use, but may experience performance degradation. While the migration takes place, nightly backups for the instance will be suspended. No other Amazon RDS operations can take place for the instance, including modifying the instance, rebooting the instance, deleting the instance, creating a Read Replica for the instance, and creating a DB snapshot of the instance.

SQL Server

You cannot change the provisioned IOPS for a SQL Server DB instance.

No

-m value

--multi-az value

Specifies if this is a Multi-AZ deployment. Changing this parameter does not result in an outage and the change is applied during the next maintenance window unless the ApplyImmediately parameter is set to true for this request. Not a valid option for SQL Server Multi-AZ mirrored instances. To configure Multi-AZ for a SQL Server instance, apply or remove the "Mirroring" option using Option Groups.

Type: Boolean

Default: false

Valid values: true | false

Constraints: Cannot be specified if the DB instance is a Read Replica.

No

-og value

--option-group value

Specifies the option group to be applied. Changing this parameter does not result in an outage except in the following case and the change is applied during the next maintenance window unless the ApplyImmediately parameter is set to true for this request. If the parameter change results in an option group that enables OEM, this change can cause a brief (sub-second) period during which new connections are rejected but existing connections are not interrupted.

Note that persistent options, such as the TDE_SQLServer option for Microsoft SQL Server, cannot be removed from an option group while DB instances are associated with the option group. Permanent options, such as the TDE option for Oracle Advanced Security TDE, can never be removed from an option group, and that option group cannot be removed from a DB instance once it is associated with a DB instance.

Type: String

No

-s value

--allocated-storage value

Amount of storage to be allocated for the DB instance, in gigabytes. Changing this parameter does not result in an outage and the change is applied during the next maintenance window unless the ApplyImmediately parameter is set to true for this request.

Type: Integer

Example: --allocated-storage 20

MySQL and PostgreSQL

Must be an integer from 5 to 6144.

Oracle

Must be an integer from 10 to 6144.

SQL Server

You cannot change the allocated storage for a SQL Server DB instance.

If you choose to migrate your DB instance from using standard storage to using Provisioned IOPS, or from using Provisioned IOPS to using standard storage, the process can take time. The duration of the migration depends on several factors such as database load, storage size, storage type (standard or Provisioned IOPS), amount of IOPS provisioned (if any), and the number of prior scale storage operations. Typical migration times are under 24 hours, but the process can take up to several days in some cases. During the migration, the DB instance will be available for use, but may experience performance degradation. While the migration takes place, nightly backups for the instance will be suspended. No other Amazon RDS operations can take place for the instance, including modifying the instance, rebooting the instance, deleting the instance, creating a Read Replica for the instance, and creating a DB snapshot of the instance.

No

-w value

--preferred-maintenance-window value

Preferred maintenance window for the DB instance.

Changing this parameter does not result in an outage, except in the following situation, and the change is asynchronously applied as soon as possible. If there are pending actions that cause a reboot, and the maintenance window is changed to include the current time, then changing this parameter will cause a reboot of the DB instance. If moving this window to the current time, there must be at least 30 minutes between the current time and end of the window to ensure pending changes are applied.

Type: String

Constraints: Must be in the format ddd:hh24:mi-ddd:hh24:mi. Times should be 24-hour Universal Time Coordinated (UTC). Must be at least 30 minutes. See example below.

Example: rds-modify-db-instance myinstance --preferred-maintenance-window Tue:04:00-Tue:04:30

No

--preferred-backup-window value

-b value

The daily time range during which automated backups are created if backups are enabled (using the --backup-retention-period). Changing this parameter does not result in an outage and the change is asynchronously applied as soon as possible.

Type: String

Constraints: Must be in the format hh24:mi-hh24:mi. Must be at least 30 minutes. Times should be 24-hour Universal Time Coordinated (UTC). Must not conflict with the --preferred-maintenance-window.

No

-tca value

--tde-credential-arn value

The ARN of the HSM HA Partition Group used for the TDE HSM option.

No

-tcp value

--tde-credential-password value

The password of the HSM HA Partition Group used for the TDE HSM option.

No

--certificate-identifier value

-cert value

Identifier of the CA certificate to be associated with DB Instance.

No

Output

The command returns a table that contains the following information:

Note

Output values list the possible values returned by CLI commands. Not all values are returned for every call to a command. If a value is null or empty, it will not be included in the command output. For example, CLI commands to create or restore a DB instance will not return the Endpoint Address value because that value is null until the DB instance has finished being created or restored.

  • DBInstanceId—User-supplied database identifier; this is the unique key that identifies a DB instance

  • Created—When the instance was created, in UTC

  • Class—The compute and memory capacity of the DB instance

  • CopyTagsToSnapshot—Specifies whether tags are copied from the DB instance to snapshots of the DB instance.

  • Engine—Name of the database engine to be used for this DB instance

  • Storage—Initially allocated storage size specified in GBs

  • Storage Type—The type of storage specified

  • Storage Encrypted—Indicates whether the DB instance is encrypted

  • KmsKeyId—If Storage Encrypted is true, the KMS key identifier for the encrypted DB instance

  • Resource Id—If Storage Encrypted is true, the region-unique, immutable identifier for the encrypted DB instance. This identifier is found in AWS CloudTrail log entries whenever the KMS key for the DB instance is accessed.

  • Master Username—The master username for the instance

  • Status—The current status of the instance. Valid values: available | backing-up | creating | deleted | deleting | failed | modifying | rebooting | resetting-master-credentials

  • Endpoint Address—Address of the DB instance

  • Port—Port used to connect to the DB instance

  • AZ—The instance's Availability Zone

  • IOPS—The provisioned storage allocated, expressed as I/O operations per second

  • Backup Retention—The number of days that automated backups are retained before deletion

  • PendingClass—The class to which the instance will be scaled during the next maintenance window, or to which it is currently being scaled if the --apply-immediately option was specified

  • PendingCredentials—The (hidden) master user password that will be applied to the DB instance

  • PendingVersion—The pending database engine version number. This column appears only in the --show-long view.

  • DB Name—Name of the initial database created when the instance was created or the Oracle System ID (SID) of the created DB instance (for the Oracle engine). For SQL Server, will always be null. This column appears only in the --show-long view.

  • Maintenance Window—The period during which patching and instance modifications will be performed. This column appears only in the --show-long view.

  • Backup Window—The daily period during which automated backups are created. This column appears only in the --show-long view.

  • Version—The version number of the database engine

  • Auto Minor Version Upgrade—Indicates that minor version upgrades will be applied to the DB instance during the maintenance window. This column appears only in the --show-long view.

  • License—The license model used for this DB instance

  • Security GroupName—DB security group name

  • Authorization Status—Status of authorization. Valid values: authorizing | authorized | revoking

  • Publicly Accessible—Indicates the accessibility option of the instance. A value of true specifies an Internet-facing instance with a publicly resolvable DNS name, which resolves to a public IP address. A value of false specifies an internal instance with a DNS name that resolves to a private IP address.

  • Group Name—Name of DB parameter group applied to

  • Apply Status—Status of applying the DB parameter group. Valid values: in-sync | pending-reboot | applying

  • Multi-AZ—Indicates if this is a Multi-AZ DB instance

  • EngineVersion—Database engine version number

  • Read Replica Source Identifier—The identifier of the source DB instance for which this DB instance acts as a Read Replica

  • Subnet Group Name—Subnet group name

  • Description—Subnet group description

  • VpcId—Identifier of the VPC associated with the subnet group

  • VPC security group Ids—Identifier of the VPC security groups associated with the instance

  • Subnet identifier—Subnet group identifier

  • Subnet Availability Zone—Availability Zone of the subnet

  • CACertificateIdentifier—Specifies the name of the CA certificate associated with the DB instance.

  • PendingCACertificateIdentifier—Specifies the name of the CA certificate to be associated with the DB instance.

Examples

Associate a Security Group with a Database Instance

This example shows how to associate a DB security group with the specified DB instance.


PROMPT> rds-modify-db-instance mydbinstance --db-security-groups mycoworkers 

            

Immediately Upgrade the Instance Class of a Database Instance

This example shows how to immediately change the instance class of a DB instance to db.m1.xlarge, with the change to take place immediately.


PROMPT> rds-modify-db-instance mydbinstance -c db.m1.xlarge --apply-immediately
                    
                

Modify the Maintenance Window for a Database Instance

This shows how to change the weekly preferred maintenance window for the DB instance to be the minimum four hour window starting Sundays at 11:15 PM, and ending Mondays at 3:15 AM.


PROMPT> rds-modify-db-instance mydbinstance -w Sun:23:15-Mon:03:15
                    
                

Change the Master Password for the Database Instance

This example shows how to change the master password for a DB instance.


PROMPT> rds-modify-db-instance mydbinstance -p a1b2c3d4
                    
                

Change the Allocated Storage for a Database Instance

This example shows how to change the allocated storage for a DB instance to 20 GB.


PROMPT> rds-modify-db-instance mydbinstance -s 20
                    
                

Change the CA certificate associated with a Database Instance

This example shows how to change the CA certificate for a DB instance.


PROMPT> rds-modify-db-instance -cert rds-ca-2015