Amazon DocumentDB
Developer Guide

CreateDBInstance

Creates a new DB instance.

Request Parameters

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

DBClusterIdentifier

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

Type: String

Required: Yes

DBInstanceClass

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

Type: String

Required: Yes

DBInstanceIdentifier

The DB 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 DB instance during the maintenance window.

Default: true

Type: Boolean

Required: No

AvailabilityZone

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

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

Example: us-east-1d

Constraint: The AvailabilityZone parameter can't be specified if the MultiAZ parameter is set to true. The specified Availability Zone must be in the same AWS Region as the current endpoint.

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 DB 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 a DB 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 DB 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 DB cluster.

HTTP Status Code: 404

DBInstanceAlreadyExists

You already have a DB instance with the given identifier.

HTTP Status Code: 400

DBParameterGroupNotFound

DBParameterGroupName doesn't refer to an existing DB parameter group.

HTTP Status Code: 404

DBSecurityGroupNotFound

DBSecurityGroupName doesn't refer to an existing DB security group.

HTTP Status Code: 404

DBSubnetGroupDoesNotCoverEnoughAZs

Subnets in the DB 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 DB subnet group.

HTTP Status Code: 404

InstanceQuotaExceeded

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

HTTP Status Code: 400

InsufficientDBInstanceCapacity

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

HTTP Status Code: 400

InvalidDBClusterStateFault

The DB 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 DB 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 DB 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: