Amazon Relational Database Service
Command Line Interface Reference (API Version 2013-09-09)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Did this page help you?  Yes | No |  Tell us about it...

rds-create-db-instance

Description

Creates a new DB instance.

Syntax

rds-create-db-instance DBInstanceIdentifier

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

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

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

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

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

[-cs (--character-set) value ]

-e (--engine) value

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

[--iops value ]

-lm (--license model) value

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

[-n (--db-name) value ]

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

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

[--port value ]

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

-s (--allocated-storage) value

[-sn (--db-subnet-group-name) value ]

-u (--master-username) value

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

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

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

[-z (--availability-zone) value ]

[General Options]

Options

NameDescriptionRequired

DBInstanceIdentifier

--db-instance-identifier value

DB instance identifier. This is the unique key that identifies a DB instance. This parameter is stored as a lowercase string. This can also be passed as a named parameter using --db-instance-identifier value

Type: String

Default: None

Constraints: Must contain from 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

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

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.cr1.8xlarge | db.m3.medium | db.m3.large | db.m3.xlarge | db.m3.2xlarge

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

Note

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

Yes

-n value

--db-name value

The meaning of this parameter differs according to the database engine you use.

MySQL and PostgreSQL

Name of a database to create when the DB instance is created. If this parameter is not specified, no database is created in the instance.

Constraints:

  • Cannot be empty.

  • Must contain 1 to 64 alphanumeric characters.

  • Cannot be a word reserved by the specified database engine.

Type: String

Example: --db-name MyDatabase

Oracle

The Oracle System ID (SID) of the created DB instance.

Constraints:

  • Cannot be longer than 8 characters.

Type: String

Example: --db-name MYORACLE

SQL Server

Not applicable.

No

-e value

--engine value

Name of the database engine to be used for this instance.

Type: String

Default: None

Valid values: MySQL | postgres |oracle-se1 | oracle-se | oracle-ee | sqlserver-ee | sqlserver-se | sqlserver-ex | sqlserver-web

Yes

-v value

--engine-version value

Version number of the database engine to use.

Type: String

MySQL

Example: --engine-version 5.5.31

PostgreSQL

Example: --engine-version 9.3

Oracle

Example: --engine-version 11.2.0.2.v6

SQL Server

Example: --engine-version 11.00.2100.60.v1

No

-g value

--db-parameter-group-name value

Name of the DB parameter group to associate with this DB instance. If this argument is omitted, the default DBParameterGroup for the specified engine will be used.

Type: String

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

No

-lm

--license-model value

License model for this DB instance.

Type: String

Default: None

Valid values: license-included | bring-your-own-license | general-public-license

Example: --license-model bring-your-own

No

-m value

--multi-az value

Specifies if this is a Multi-AZ deployment.

Note

At this time, multi-AZ deployments are not supported for the Microsoft SQL Server database engine.

Type: Boolean

Default: false

Constraints: The --availability-zone parameter cannot be set if the --multi-az parameter is set to true.

Valid values: true | false

No

--iops value

Specifies the amount of provisioned IOPS for the DB instance, expressed in I/O operations per second.

Constraints: Must be an integer greater than 1000.

No

-a value

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

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

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

--port value

Port number that the DB instance uses for connections.

Type: Integer

MySQL

Default: 3306

Valid Values: 1150-65535

Type: Integer

PostgreSQL

Default: 5432

Valid Values: 1150-65535

Type: Integer

Oracle

Default: 1521

Valid Values: 1150-65535

Type: Integer

Example: --port 1234

SQL Server

Default: 1433

Valid Values: 1150-65535 except for 1434, 3389, 47001, 49152, and 49152 through 49156.

Type: Integer

No

-s value

--allocated-storage value

Amount of storage to be initially allocated for the DB instance, in gigabytes.

Type: String

MySQL

Constraints: Must be an integer between 5 and 1024.

Oracle

Constraints: Must be an integer between 10 and 1024.

SQL Server

Constraints: Must be an integer from 200 to 1024 (sqlserver-se and sqlserver-ee) or from 30 to 1024 (sqlserver-ex and sqlserver-web).

Example: --allocated-storage 320

Yes

-au value

--auto-minor-version-upgrade value

Indicates that minor version upgrades will be applied automatically to the DB instance during the maintenance window.

Type: Boolean

Default: true

Example: -au true

No

-u value

--master-username value

The name of the master database user.

Type: String

MySQL

Constraints:

  • Must be an alphanumeric string containing from 1 to 16 characters

  • First character must be a letter

  • Cannot be a reserved word for the chosen database engine

Oracle

Constraints:

  • Must be an alphanumeric string containing from 1 to 30 characters

  • First character must be a letter

  • Cannot be a reserved word for the chosen database engine

SQL Server

Constraints:

  • Must be 1 to 128 alphanumeric characters.

  • First character must be a letter.

  • Cannot be a reserved word for the chosen database engine.

Example: --master-username SQLDBA1

Yes

-og value

--option-group value

The name of the option group to be associated with this instance. If this parameter is not provided, the default option group for the engine specified is used.

Note that persistent options, such as the TDE 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.

No

-p value

--master-user-password value

Password for the master DB instance user. Can be any printable ASCII character except "/" or "@". If this parameter is not provided, the user will be prompted to enter a password.

MySQL

Constraints: Must contain from 8 to 41 characters.

Type: String

Oracle

Constraints: Must contain from 8 to 30 characters.

Type: String

SQL Server

Constraints: Must contain from 8 to 128 characters.

Example: --master-user-password mysecretpassword01

No

-w value

--preferred-maintenance-window value

Weekly time range (in UTC) during which system maintenance can occur.

Type: String

Default: A 30-minute window selected at random from an 8-hour block of time per region, occurring on a random day of the week. The following list shows the time blocks for each region from which the default maintenance windows are assigned.

Default: Depends on the Region the database was created in. The following table lists the default maintenance window for each Region.

RegionTime Block
US East (Northern Virginia) Region03:00-11:00 UTC
US West (Northern California) Region06:00-14:00 UTC
US West (Oregon) Region06:00-14:00 UTC
EU (Ireland) Region22:00-06:00 UTC
Asia Pacific (Tokyo) Region17:00-03:00 UTC
Asia Pacific (Sydney) Region12:00-20:00 UTC
Asia Pacific (Singapore) Region14:00-22:00 UTC
South America (São Paulo) Region00:00-08:00 UTC
AWS GovCloud (US) Region06:00-14:00 UTC

Constraints:

  • Must not conflict with the preferred backup window for this DB instance.

  • Must be at least 30 minutes.

  • Must be in the format ddd:hh24:mi-ddd:hh24:mi.

  • Times should be Universal Time Coordinated (UTC). See example below.

Example: --preferred-maintenance-window Tue:00:30-Tue:04:30

No

-b value

--preferred-backup-window value

The daily time range (in UTC) during which automated backups are created if backups are enabled (using the --backup-retention-period) parameter.

Type: String

Default: A 30-minute window selected at random from an 8-hour block of time per region. The following table lists the time blocks for each region from which the default backup windows are assigned.

Default: Depends on the Region the database was created in. The following table lists the default backup window for each Region.

RegionTime Block
US East (Northern Virginia) Region03:00-11:00 UTC
US West (Northern California) Region06:00-14:00 UTC
US West (Oregon) Region06:00-14:00 UTC
EU (Ireland) Region22:00-06:00 UTC
Asia Pacific (Tokyo) Region17:00-03:00 UTC
Asia Pacific (Sydney) Region12:00-20:00 UTC
Asia Pacific (Singapore) Region14:00-22:00 UTC
South America (São Paulo) Region00:00-08:00 UTC
AWS GovCloud (US) Region03:00-11:00 UTC

Constraints:

  • Must not conflict with the preferred maintenance window for this DB instance.

  • Must be in the format hh24:mi-hh24:mi.

  • Times should be 24-hour Universal Time Coordinated (UTC).

  • Must not conflict with the --preferred-maintenance-window.

  • Must be at least 30 minutes.

No

-r value

--backup-retention-period value

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

Type: Integer

Default: 1

Constraints:

  • Must be a value from 0 to 35.

  • Cannot be set to 0 if the DB instance is a source to read replicas.

No

-z value

--availability-zone value

The Amazon EC2 Availability Zone that the DB instance will be created in.

Type: String

Default: A random, system-chosen Availability Zone in the same region as the current endpoint.

Constraints: The --availability-zone parameter cannot be set if the --multi-az parameter is set to true.

Example: --availability-zone us-east-1a

No

-sn value

--db-subnet-group-name value

The name of the DB subnet group to associate with this DB instance. Specifying a DB subnet group will create this DB instance in the VPC associated with the DB subnet group.

Type: String

Default: none

Constraints: Must be the name of an existing DB subnet group.

Example: --db-subnet-group-name mydbsubnetgroup

No

-pub value

--publicly-accessible value

Specifies the accessibility options for the DB 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.

 

-cs value

--character-set value

Specifies the Oracle character set that the DB instance will use. For a list of supported character sets, go to Appendix: Oracle Character Sets Supported in Amazon RDS. Oracle only.

 

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—The user-supplied DB instance identifier

  • Created—The data and time the instance was created, in 24-hour UTC

  • Class—The compute and memory capacity of the instance

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

  • License Model—The license model used for this DB instance

  • Storage—Initially allocated storage size specified in gigabytes (GBs)

  • Master Username—The master username for the DB instance

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

  • Endpoint Address—Address of the DB instance

  • Port—Port used to connect to the DB instance

  • AZ—The instance's Availability Zone

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

  • PendingBackupRetention—The backup retention period which will be applied at the next maintenance window, or which is currently being applied if the --apply-immediately option was specified

  • 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

  • PendingStorage—The storage size 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

  • PendingMulti-AZ—If true, indicates the instance will be converted to run as a Multi-AZ deployment; if false, the instance will be converted to run as a standard (Single-AZ) deployment.

  • PendingVersion—The engine version of the pending database instance.

  • SecondaryAvailabilityZone—If present, specifies the name of the secondary Availability Zone for a DB instance with multi-AZ support.

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

  • 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 period during which automated backups are created. This column appears only in the --show-long view

  • Latest Restorable Time—The latest time to which a database can be restored using point-in-time restore. This column appears only in the --show-long view.

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

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

  • EngineVersion—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.

  • Name—The DB security group name

  • Group Name—Name of DB parameter group applied to

  • Apply Status—Status of applying the parameter group. It can be either in-sync or pending-reboot

  • read replica ID—The identifier of a DB instance which acts as a read replica of this DB instance

  • 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

Examples

Create a Database Instance with Minimal Parameters

This example creates a DB instance with the minimal set of parameters.

PROMPT> rds-create-db-instance SimCoProd01 -s 10 -c db.m1.large -e mysql -u master -p Kew2401Sd
                

Create an Oracle Database Instance

This example creates a DB instance with the minimal set of parameters.

PROMPT> rds-create-db-instance SimCoProd01 -s 10 -c db.m1.large -e oracle-se --db-name MYORACLE -lm bring-your-own-license -u master -p Kew2401Sd
                

Create a Database Instance and Prompt for a Password

This example creates a database, prompting for the master user password.

PROMPT> rds-create-db-instance SimCoProd02 -s 10 -c db.m1.large -e mysql -u master -p