CreateDBInstance

Creates a new instance.

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters.

DBClusterIdentifier

The identifier of the cluster that the instance will belong to.

Type: String

Required: Yes

DBInstanceClass

The compute and memory capacity of the instance; for example, db.r5.large.

Type: String

Required: Yes

DBInstanceIdentifier

The instance identifier. This parameter is stored as a lowercase string.

Constraints:

  • Must contain from 1 to 63 letters, numbers, or hyphens.

  • The first character must be a letter.

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

Example: mydbinstance

Type: String

Required: Yes

Engine

The name of the database engine to be used for this instance.

Valid value: docdb

Type: String

Required: Yes

AutoMinorVersionUpgrade

Indicates that minor engine upgrades are applied automatically to the instance during the maintenance window.

Default: true

Type: Boolean

Required: No

AvailabilityZone

The Amazon EC2 Availability Zone that the instance is created in.

Default: A random, system-chosen Availability Zone in the endpoint’s AWS Region.

Example: us-east-1d

Type: String

Required: No

PreferredMaintenanceWindow

The time range each week during which system maintenance can occur, in Universal Coordinated Time (UTC).

Format: ddd:hh24:mi-ddd:hh24:mi

The default is a 30-minute window selected at random from an 8-hour block of time for each AWS Region, occurring on a random day of the week.

Valid days: Mon, Tue, Wed, Thu, Fri, Sat, Sun

Constraints: Minimum 30-minute window.

Type: String

Required: No

PromotionTier

A value that specifies the order in which an Amazon DocumentDB replica is promoted to the primary instance after a failure of the existing primary instance.

Default: 1

Valid values: 0-15

Type: Integer

Required: No

Tags.Tag.N

The tags to be assigned to the instance. You can assign up to 10 tags to an instance.

Type: Array of Tag objects

Required: No

Response Elements

The following element is returned by the service.

DBInstance

Detailed information about an instance.

Type: DBInstance object

Errors

For information about the errors that are common to all actions, see Common Errors.

AuthorizationNotFound

The specified CIDR IP or Amazon EC2 security group isn’t authorized for the specified security group.

Amazon DocumentDB also might not be authorized to perform necessary actions on your behalf using IAM.

HTTP Status Code: 404

DBClusterNotFoundFault

DBClusterIdentifier doesn’t refer to an existing cluster.

HTTP Status Code: 404

DBInstanceAlreadyExists

You already have a instance with the given identifier.

HTTP Status Code: 400

DBParameterGroupNotFound

DBParameterGroupName doesn’t refer to an existing parameter group.

HTTP Status Code: 404

DBSecurityGroupNotFound

DBSecurityGroupName doesn’t refer to an existing security group.

HTTP Status Code: 404

DBSubnetGroupDoesNotCoverEnoughAZs

Subnets in the subnet group should cover at least two Availability Zones unless there is only one Availability Zone.

HTTP Status Code: 400

DBSubnetGroupNotFoundFault

DBSubnetGroupName doesn’t refer to an existing subnet group.

HTTP Status Code: 404

InstanceQuotaExceeded

The request would cause you to exceed the allowed number of instances.

HTTP Status Code: 400

InsufficientDBInstanceCapacity

The specified instance class isn’t available in the specified Availability Zone.

HTTP Status Code: 400

InvalidDBClusterStateFault

The cluster isn’t in a valid state.

HTTP Status Code: 400

InvalidSubnet

The requested subnet is not valid, or multiple subnets were requested that are not all in a common virtual private cloud (VPC).

HTTP Status Code: 400

InvalidVPCNetworkStateFault

The subnet group doesn’t cover all Availability Zones after it is created because of changes that were made.

HTTP Status Code: 400

KMSKeyNotAccessibleFault

An error occurred when accessing an AWS KMS key.

HTTP Status Code: 400

StorageQuotaExceeded

The request would cause you to exceed the allowed amount of storage available across all instances.

HTTP Status Code: 400

StorageTypeNotSupported

Storage of the specified StorageType can’t be associated with the DB instance.

HTTP Status Code: 400

See Also

For more information about using this API in one of the language-specific AWS SDKs, see the following: