- Navigation GuideYou are on a Command (operation) page with structural examples. Use the navigation breadcrumb if you would like to return to the Client landing page.
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
Parameter | Type | Description |
---|
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, |
DBInstanceIdentifier Required | string | undefined | The instance identifier. This parameter is stored as a lowercase string. Constraints:
Example: |
Engine Required | string | undefined | The name of the database engine to be used for this instance. Valid value: |
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: |
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: |
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: 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 |
---|
Parameter | Type | Description |
---|---|---|
$metadata Required | ResponseMetadata | Metadata pertaining to this request. |
DBInstance | DBInstance | undefined | Detailed information about an instance. |
Throws
Name | Fault | Details |
---|
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 | |
DBInstanceAlreadyExistsFault | client | You already have a instance with the given identifier. |
DBParameterGroupNotFoundFault | client | |
DBSecurityGroupNotFoundFault | client | |
DBSubnetGroupDoesNotCoverEnoughAZs | client | Subnets in the subnet group should cover at least two Availability Zones unless there is only one Availability Zone. |
DBSubnetGroupNotFoundFault | client | |
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 |
DocDBServiceException | Base exception class for all service exceptions from DocDB service. |