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

rds-create-db-instance-read-replica

The Amazon RDS Command Line Interface (RDS CLI) has been deprecated. Instead, use the AWS CLI for RDS. To learn how to download and use the AWS CLI, see AWS Command Line Interface User Guide. For RDS commands available in the AWS CLI, see AWS CLI Reference for Amazon RDS.

The AWS CLI does not currently support the DownloadCompleteDBLogFile REST API action. To download an entire log file at once, rather than in parts using the download-db-log-file-portion command, use the last published RDS CLI and the rds-download-db-logfile command.

Description

Creates a DB instance that acts as a Read Replica of a source DB instance.

Note

Read Replicas are only supported for the MySQL and PostgreSQL DB engines.

All Read Replica DB instances are created as Single-AZ deployments with backups disabled. All other DB instance attributes (including DB security groups and DB parameter groups) are inherited from the source DB instance, except where specified otherwise.

Syntax

rds-create-db-instance-read-replica db-instance-identifier

-s (--source-db-instance-identifier) value

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

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

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

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

[--iops value ]

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

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

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

[-p (--port) value ]

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

[-tk (--tag-key) value ]

[-tv (--tag-value) value ]

[General Options]

Options

Name Description Required

--db-instance-identifier value

-i value

DB instance identifier of the Read Replica. This is the unique key that identifies a DB instance. This parameter is 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-create-db-instance-read-replica my-db-instance-identifier.

Type: String

Default: None

Constraints:

  • Must contain from 1 to 63 alphanumeric characters or hyphens.

  • First character must be a letter.

  • Cannot end with a hyphen or contain two consecutive hyphens.

Example: myinstance

Yes

-s value

--source-db-instance-identifier value

The identifier of the DB instance for which this DB instance will act as a Read Replica. You can have up to 5 Read Replicas per DB instance.

Type: String

Constraints:

  • If the source DB instance is in the same region as the Read Replica, must be the identifier of an existing DB instance. If the source is in a different region, must specify the ARN of the source instance. For more information about ARNs, go to Constructing an Amazon RDS Amazon Resource Name (ARN).

  • Can specify a DB instance that is a Read Replica only if the source is running MySQL 5.6, PostgreSQL 9.3.5, 9.3.6, 9.3.9, 9.3.10, 9.4.1, 9.4.4, and 9.4.5.

  • The specified source DB instance must have backups enabled, its backup retention period must be greater than 0.

Yes

-c value

--db-instance-class value

Contains the compute and memory capacity of the Read Replica.

Type: String

Default: Inherits from the source 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.

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 Read Replica to snapshots of the Read Replica; otherwise false. The default is false.

No

-og value

--option-group value

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

No

-p value

--port value

Port number that the Read Replica uses for connections.

Type: Integer

Default: Inherits from the source DB instance

Example: --port 1234

No

-au value

--auto-minor-version-upgrade value

Indicates that minor engine upgrades will be applied automatically to the Read Replica during the maintenance window.

Type: Boolean

Default: Inherits from the source DB instance

Example: -au true

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 amount of provisioned IOPS for the DB instance, expressed in I/O operations per second.

If this parameter is not specified, the IOPS value will be taken from the master. If this parameter is set to 0, the new instance will not have provisioned IOPS.

Constraints: Must be an integer greater than 1000.

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.

No

-z value

--availability-zone value

The Amazon EC2 Availability Zone that the Read Replica 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

-n value

--db-subnet-group-name value

The name of a DB subnet group associated with the Amazon VPC in which you want the Read Replica to be created. If a DB subnet group name is not specified, the Read Replica will be created outside of any VPC.

Type: String

Default: none.

Constraints:

  • Can only be specified if --source-db-instance-identifier references an instance in another region.

  • The specified DB subnet group must be in the same region in which the command is running. For example, if you specify --region us-west-2, then the DB subnet group must be in the us-west-2 region.

  • All of the Read Replicas in one region that are created from the same source DB instance in another region must either:

    • Specify DB subnet groups from the same VPC. These Read Replicas will be created in the same VPC.

    • Not specify a DB subnet group. These Read Replicas will be created outside of any VPC.

No

--tag-key

-tk

The name of a tag to add for the new Read Replica.

No

--tag-value

-tv

The value of the tag to add for the new Read Replica.

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

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

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

  • Endpoint Address—Address of the DB instance

  • Port—Port used to connect to the DB instance

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

  • AZ—The instance's Availability Zone

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

  • PendingBackupRetention—The backup retention period that will be applied at the next maintenance window, or that 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 that 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.

  • DB Name—Name of the initial database created when the instance was created. 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.

  • 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

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

  • 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 the source DB instance for which this DB instance acts as a Read Replica

Examples

Create a Read Replica with Minimal Parameters

This example creates a Read Replica with the minimal set of parameters.

Copy
PROMPT> rds-create-db-instance-read-replica SimCoProd01Replica01 -s SimcoProd01 DBINSTANCE simcoprod01replica01 db.m1.large mysql 10 master creating us-east-1b 0 n 5.1.50 simcoprod01 SECGROUP default active PARAMGRP default.mysql5.1 in-sync DBINSTANCE simcoprod01replica01 db.m1.large mysql 10 master creating cn-north-1a 0 n 5.1.50 simcoprod01 SECGROUP default active PARAMGRP default.mysql5.1 in-sync

Create a Read Replica and Specify an Availability Zone

This example creates a Read Replica, specifying an availability zone.

Copy
PROMPT> rds-create-db-instance-read-replica SimCoProd01Replica02 -s SimCoProd01-z us-east-1a DBINSTANCE simcoprod01replica02 db.m1.large mysql 10 master creating us-east-1a 0 n 5.1.50 simcoprod01 SECGROUP default active PARAMGRP default.mysql5.1 in-sync