CreateDBInstanceCommand

Creates a new instance.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { DocDBClient, CreateDBInstanceCommand } from "@aws-sdk/client-docdb"; // ES Modules import
// const { DocDBClient, CreateDBInstanceCommand } = require("@aws-sdk/client-docdb"); // CommonJS import
const client = new DocDBClient(config);
const input = { // CreateDBInstanceMessage
  DBInstanceIdentifier: "STRING_VALUE", // required
  DBInstanceClass: "STRING_VALUE", // required
  Engine: "STRING_VALUE", // required
  AvailabilityZone: "STRING_VALUE",
  PreferredMaintenanceWindow: "STRING_VALUE",
  AutoMinorVersionUpgrade: true || false,
  Tags: [ // TagList
    { // Tag
      Key: "STRING_VALUE",
      Value: "STRING_VALUE",
    },
  ],
  DBClusterIdentifier: "STRING_VALUE", // required
  CopyTagsToSnapshot: true || false,
  PromotionTier: Number("int"),
  EnablePerformanceInsights: true || false,
  PerformanceInsightsKMSKeyId: "STRING_VALUE",
  CACertificateIdentifier: "STRING_VALUE",
};
const command = new CreateDBInstanceCommand(input);
const response = await client.send(command);
// { // CreateDBInstanceResult
//   DBInstance: { // DBInstance
//     DBInstanceIdentifier: "STRING_VALUE",
//     DBInstanceClass: "STRING_VALUE",
//     Engine: "STRING_VALUE",
//     DBInstanceStatus: "STRING_VALUE",
//     Endpoint: { // Endpoint
//       Address: "STRING_VALUE",
//       Port: Number("int"),
//       HostedZoneId: "STRING_VALUE",
//     },
//     InstanceCreateTime: new Date("TIMESTAMP"),
//     PreferredBackupWindow: "STRING_VALUE",
//     BackupRetentionPeriod: Number("int"),
//     VpcSecurityGroups: [ // VpcSecurityGroupMembershipList
//       { // VpcSecurityGroupMembership
//         VpcSecurityGroupId: "STRING_VALUE",
//         Status: "STRING_VALUE",
//       },
//     ],
//     AvailabilityZone: "STRING_VALUE",
//     DBSubnetGroup: { // DBSubnetGroup
//       DBSubnetGroupName: "STRING_VALUE",
//       DBSubnetGroupDescription: "STRING_VALUE",
//       VpcId: "STRING_VALUE",
//       SubnetGroupStatus: "STRING_VALUE",
//       Subnets: [ // SubnetList
//         { // Subnet
//           SubnetIdentifier: "STRING_VALUE",
//           SubnetAvailabilityZone: { // AvailabilityZone
//             Name: "STRING_VALUE",
//           },
//           SubnetStatus: "STRING_VALUE",
//         },
//       ],
//       DBSubnetGroupArn: "STRING_VALUE",
//     },
//     PreferredMaintenanceWindow: "STRING_VALUE",
//     PendingModifiedValues: { // PendingModifiedValues
//       DBInstanceClass: "STRING_VALUE",
//       AllocatedStorage: Number("int"),
//       MasterUserPassword: "STRING_VALUE",
//       Port: Number("int"),
//       BackupRetentionPeriod: Number("int"),
//       MultiAZ: true || false,
//       EngineVersion: "STRING_VALUE",
//       LicenseModel: "STRING_VALUE",
//       Iops: Number("int"),
//       DBInstanceIdentifier: "STRING_VALUE",
//       StorageType: "STRING_VALUE",
//       CACertificateIdentifier: "STRING_VALUE",
//       DBSubnetGroupName: "STRING_VALUE",
//       PendingCloudwatchLogsExports: { // PendingCloudwatchLogsExports
//         LogTypesToEnable: [ // LogTypeList
//           "STRING_VALUE",
//         ],
//         LogTypesToDisable: [
//           "STRING_VALUE",
//         ],
//       },
//     },
//     LatestRestorableTime: new Date("TIMESTAMP"),
//     EngineVersion: "STRING_VALUE",
//     AutoMinorVersionUpgrade: true || false,
//     PubliclyAccessible: true || false,
//     StatusInfos: [ // DBInstanceStatusInfoList
//       { // DBInstanceStatusInfo
//         StatusType: "STRING_VALUE",
//         Normal: true || false,
//         Status: "STRING_VALUE",
//         Message: "STRING_VALUE",
//       },
//     ],
//     DBClusterIdentifier: "STRING_VALUE",
//     StorageEncrypted: true || false,
//     KmsKeyId: "STRING_VALUE",
//     DbiResourceId: "STRING_VALUE",
//     CACertificateIdentifier: "STRING_VALUE",
//     CopyTagsToSnapshot: true || false,
//     PromotionTier: Number("int"),
//     DBInstanceArn: "STRING_VALUE",
//     EnabledCloudwatchLogsExports: [
//       "STRING_VALUE",
//     ],
//     CertificateDetails: { // CertificateDetails
//       CAIdentifier: "STRING_VALUE",
//       ValidTill: new Date("TIMESTAMP"),
//     },
//     PerformanceInsightsEnabled: true || false,
//     PerformanceInsightsKMSKeyId: "STRING_VALUE",
//   },
// };

CreateDBInstanceCommand Input

See CreateDBInstanceCommandInput for more details

Parameter
Type
Description
DBClusterIdentifier
Required
string | undefined

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

DBInstanceClass
Required
string | undefined

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

DBInstanceIdentifier
Required
string | undefined

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

Engine
Required
string | undefined

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

Valid value: docdb

AutoMinorVersionUpgrade
boolean | undefined

This parameter does not apply to Amazon DocumentDB. Amazon DocumentDB does not perform minor version upgrades regardless of the value set.

Default: false

AvailabilityZone
string | undefined

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

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

Example: us-east-1d

CACertificateIdentifier
string | undefined

The CA certificate identifier to use for the DB instance's server certificate.

For more information, see Updating Your Amazon DocumentDB TLS Certificates  and Encrypting Data in Transit  in the Amazon DocumentDB Developer Guide.

CopyTagsToSnapshot
boolean | undefined

A value that indicates whether to copy tags from the DB instance to snapshots of the DB instance. By default, tags are not copied.

EnablePerformanceInsights
boolean | undefined

A value that indicates whether to enable Performance Insights for the DB Instance. For more information, see Using Amazon Performance Insights .

PerformanceInsightsKMSKeyId
string | undefined

The KMS key identifier for encryption of Performance Insights data.

The KMS key identifier is the key ARN, key ID, alias ARN, or alias name for the KMS key.

If you do not specify a value for PerformanceInsightsKMSKeyId, then Amazon DocumentDB uses your default KMS key. There is a default KMS key for your Amazon Web Services account. Your Amazon Web Services account has a different default KMS key for each Amazon Web Services region.

PreferredMaintenanceWindow
string | undefined

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 Amazon Web Services Region, occurring on a random day of the week.

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

Constraints: Minimum 30-minute window.

PromotionTier
number | undefined

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

Tags
Tag[] | undefined

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

CreateDBInstanceCommand Output

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
DBInstance
DBInstance | undefined

Detailed information about an instance.

Throws

Name
Fault
Details
AuthorizationNotFoundFault
client

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.

DBClusterNotFoundFault
client

DBClusterIdentifier doesn't refer to an existing cluster.

DBInstanceAlreadyExistsFault
client

You already have a instance with the given identifier.

DBParameterGroupNotFoundFault
client

DBParameterGroupName doesn't refer to an existing parameter group.

DBSecurityGroupNotFoundFault
client

DBSecurityGroupName doesn't refer to an existing security group.

DBSubnetGroupDoesNotCoverEnoughAZs
client

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

DBSubnetGroupNotFoundFault
client

DBSubnetGroupName doesn't refer to an existing subnet group.

InstanceQuotaExceededFault
client

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

InsufficientDBInstanceCapacityFault
client

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

InvalidDBClusterStateFault
client

The cluster isn't in a valid state.

InvalidSubnet
client

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

InvalidVPCNetworkStateFault
client

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

KMSKeyNotAccessibleFault
client

An error occurred when accessing an KMS key.

StorageQuotaExceededFault
client

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

StorageTypeNotSupportedFault
client

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

DocDBServiceException
Base exception class for all service exceptions from DocDB service.