db_instances

Creates, updates, deletes, gets or lists a db_instances resource.

Overview

Name	db_instances
Type	Resource
Id	aws.docdb.db_instances

Fields

The following fields are returned by SELECT queries:

describe_db_instances

Name	Datatype	Description
auto_minor_version_upgrade	boolean	Does not apply. This parameter does not apply to Amazon DocumentDB. Amazon DocumentDB does not perform minor version upgrades regardless of the value set.
availability_zone	string	Specifies the name of the Availability Zone that the instance is located in.
backup_retention_period	integer	Specifies the number of days for which automatic snapshots are retained.
ca_certificate_identifier	string	The identifier of the CA certificate for this DB instance.
certificate_details	string	The details of the DB instance's server certificate.
copy_tags_to_snapshot	boolean	A value that indicates whether to copy tags from the DB instance to snapshots of the DB instance. By default, tags are not copied.
db_cluster_identifier	string	Contains the name of the cluster that the instance is a member of if the instance is a member of a cluster.
db_instance_arn	string	The Amazon Resource Name (ARN) for the instance.
db_instance_class	string	Contains the name of the compute and memory capacity class of the instance.
db_instance_identifier	string	Contains a user-provided database identifier. This identifier is the unique key that identifies an instance.
db_instance_status	string	Specifies the current state of this database.
db_subnet_group	string	Specifies information on the subnet group that is associated with the instance, including the name, description, and subnets in the subnet group.
dbi_resource_id	string	The Amazon Web Services Region-unique, immutable identifier for the instance. This identifier is found in CloudTrail log entries whenever the KMS key for the instance is accessed.
enabled_cloudwatch_logs_exports	string	A list of log types that this instance is configured to export to CloudWatch Logs.
endpoint	string	Specifies the connection endpoint.
engine	string	Provides the name of the database engine to be used for this instance.
engine_version	string	Indicates the database engine version.
instance_create_time	string	Provides the date and time that the instance was created.
kms_key_id	string	If StorageEncrypted is true, the KMS key identifier for the encrypted instance.
latest_restorable_time	string	Specifies the latest time to which a database can be restored with point-in-time restore.
pending_modified_values	string	Specifies that changes to the instance are pending. This element is included only when changes are pending. Specific changes are identified by subelements.
performance_insights_enabled	boolean	Set to true if Amazon RDS Performance Insights is enabled for the DB instance, and otherwise false.
performance_insights_kms_key_id	string	The KMS key identifier for encryption of Performance Insights data. The KMS key ID is the Amazon Resource Name (ARN), KMS key identifier, or the KMS key alias for the KMS encryption key.
preferred_backup_window	string	Specifies the daily time range during which automated backups are created if automated backups are enabled, as determined by the BackupRetentionPeriod.
preferred_maintenance_window	string	Specifies the weekly time range during which system maintenance can occur, in Universal Coordinated Time (UTC).
promotion_tier	integer	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.
publicly_accessible	boolean	Not supported. Amazon DocumentDB does not currently support public endpoints. The value of PubliclyAccessible is always false.
status_infos	string	The status of a read replica. If the instance is not a read replica, this is blank.
storage_encrypted	boolean	Specifies whether or not the instance is encrypted.
vpc_security_groups	string	Provides a list of VPC security group elements that the instance belongs to.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_db_instances	select	region	DBInstanceIdentifier, Filters, MaxRecords, Marker	Returns information about provisioned Amazon DocumentDB instances. This API supports pagination.
create_db_instance	insert	DBInstanceIdentifier, DBInstanceClass, DBClusterIdentifier, region	Engine, AvailabilityZone, PreferredMaintenanceWindow, AutoMinorVersionUpgrade, Tags, CopyTagsToSnapshot, PromotionTier, EnablePerformanceInsights, PerformanceInsightsKMSKeyId, CACertificateIdentifier	Creates a new instance.
modify_db_instance	update	DBInstanceIdentifier, region	DBInstanceClass, ApplyImmediately, PreferredMaintenanceWindow, AutoMinorVersionUpgrade, NewDBInstanceIdentifier, CACertificateIdentifier, CopyTagsToSnapshot, PromotionTier, EnablePerformanceInsights, PerformanceInsightsKMSKeyId, CertificateRotationRestart	Modifies settings for an instance. You can change one or more database configuration parameters by specifying these parameters and the new values in the request.
delete_db_instance	delete	DBInstanceIdentifier, region		Deletes a previously provisioned instance.
reboot_db_instance	exec	DBInstanceIdentifier, region	ForceFailover	You might need to reboot your instance, usually for maintenance reasons. For example, if you make certain changes, or if you change the cluster parameter group that is associated with the instance, you must reboot the instance for the changes to take effect. Rebooting an instance restarts the database engine service. Rebooting an instance results in a momentary outage, during which the instance status is set to rebooting.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
DBClusterIdentifier	string	The identifier of the cluster that the instance will belong to.
DBInstanceClass	string	The compute and memory capacity of the instance; for example, db.r5.large.
DBInstanceIdentifier	string	The instance identifier. This parameter is stored as a lowercase string. Constraints: Must match the identifier of an existing DBInstance.
region	string	AWS region (default: us-east-1)
ApplyImmediately	boolean	Specifies whether the modifications in this request and any pending modifications are asynchronously applied as soon as possible, regardless of the PreferredMaintenanceWindow setting for the instance. If this parameter is set to false, changes to the instance are applied during the next maintenance window. Some parameter changes can cause an outage and are applied on the next reboot. Default: false
AutoMinorVersionUpgrade	boolean	This parameter does not apply to Amazon DocumentDB. Amazon DocumentDB does not perform minor version upgrades regardless of the value set.
AvailabilityZone	string	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	Indicates the certificate that needs to be associated with the instance.
CertificateRotationRestart	boolean	Specifies whether the DB instance is restarted when you rotate your SSL/TLS certificate. By default, the DB instance is restarted when you rotate your SSL/TLS certificate. The certificate is not updated until the DB instance is restarted. Set this parameter only if you are not using SSL/TLS to connect to the DB instance. If you are using SSL/TLS to connect to the DB instance, see Updating Your Amazon DocumentDB TLS Certificates and Encrypting Data in Transit in the Amazon DocumentDB Developer Guide.
CopyTagsToSnapshot	boolean	A value that indicates whether to copy all tags from the DB instance to snapshots of the DB instance. By default, tags are not copied.
DBInstanceClass	string	The new compute and memory capacity of the instance; for example, db.r5.large. Not all instance classes are available in all Amazon Web Services Regions. If you modify the instance class, an outage occurs during the change. The change is applied during the next maintenance window, unless ApplyImmediately is specified as true for this request. Default: Uses existing setting.
DBInstanceIdentifier	string	The user-provided instance identifier. If this parameter is specified, information from only the specific instance is returned. This parameter isn't case sensitive. Constraints: If provided, must match the identifier of an existing DBInstance.
EnablePerformanceInsights	boolean	A value that indicates whether to enable Performance Insights for the DB Instance. For more information, see Using Amazon Performance Insights.
Engine	string	The name of the database engine to be used for this instance. Valid value: docdb
Filters	array	A filter that specifies one or more instances to describe. Supported filters: db-cluster-id - Accepts cluster identifiers and cluster Amazon Resource Names (ARNs). The results list includes only the information about the instances that are associated with the clusters that are identified by these ARNs. db-instance-id - Accepts instance identifiers and instance ARNs. The results list includes only the information about the instances that are identified by these ARNs.
ForceFailover	boolean	When true, the reboot is conducted through a Multi-AZ failover. Constraint: You can't specify true if the instance is not configured for Multi-AZ.
Marker	string	An optional pagination token provided by a previous request. If this parameter is specified, the response includes only records beyond the marker, up to the value specified by MaxRecords.
MaxRecords	integer	The maximum number of records to include in the response. If more records exist than the specified MaxRecords value, a pagination token (marker) is included in the response so that the remaining results can be retrieved. Default: 100 Constraints: Minimum 20, maximum 100.
NewDBInstanceIdentifier	string	The new instance identifier for the instance when renaming an instance. When you change the instance identifier, an instance reboot occurs immediately if you set Apply Immediately to true. It occurs during the next maintenance window if you set Apply Immediately to false. This value 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
PerformanceInsightsKMSKeyId	string	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	The weekly time range (in UTC) during which system maintenance can occur, which might result in an outage. Changing this parameter doesn't result in an outage except in the following situation, and the change is asynchronously applied as soon as possible. If there are pending actions that cause a reboot, and the maintenance window is changed to include the current time, changing this parameter causes a reboot of the instance. If you are moving this window to the current time, there must be at least 30 minutes between the current time and end of the window to ensure that pending changes are applied. Default: Uses existing setting. Format: ddd:hh24:mi-ddd:hh24:mi Valid days: Mon, Tue, Wed, Thu, Fri, Sat, Sun Constraints: Must be at least 30 minutes.
PromotionTier	integer	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	array	The tags to be assigned to the instance. You can assign up to 10 tags to an instance.

SELECT examples

describe_db_instances

Returns information about provisioned Amazon DocumentDB instances. This API supports pagination.

SELECT
auto_minor_version_upgrade,
availability_zone,
backup_retention_period,
ca_certificate_identifier,
certificate_details,
copy_tags_to_snapshot,
db_cluster_identifier,
db_instance_arn,
db_instance_class,
db_instance_identifier,
db_instance_status,
db_subnet_group,
dbi_resource_id,
enabled_cloudwatch_logs_exports,
endpoint,
engine,
engine_version,
instance_create_time,
kms_key_id,
latest_restorable_time,
pending_modified_values,
performance_insights_enabled,
performance_insights_kms_key_id,
preferred_backup_window,
preferred_maintenance_window,
promotion_tier,
publicly_accessible,
status_infos,
storage_encrypted,
vpc_security_groups
FROM aws.docdb.db_instances
WHERE region = '{{ region }}' -- required
AND DBInstanceIdentifier = '{{ DBInstanceIdentifier }}'
AND Filters = '{{ Filters }}'
AND MaxRecords = '{{ MaxRecords }}'
AND Marker = '{{ Marker }}'
;

INSERT examples

create_db_instance

Creates a new instance.

INSERT INTO aws.docdb.db_instances (
DBInstanceIdentifier,
DBInstanceClass,
DBClusterIdentifier,
region,
Engine,
AvailabilityZone,
PreferredMaintenanceWindow,
AutoMinorVersionUpgrade,
Tags,
CopyTagsToSnapshot,
PromotionTier,
EnablePerformanceInsights,
PerformanceInsightsKMSKeyId,
CACertificateIdentifier
)
SELECT 
'{{ DBInstanceIdentifier }}',
'{{ DBInstanceClass }}',
'{{ DBClusterIdentifier }}',
'{{ region }}',
'{{ Engine }}',
'{{ AvailabilityZone }}',
'{{ PreferredMaintenanceWindow }}',
'{{ AutoMinorVersionUpgrade }}',
'{{ Tags }}',
'{{ CopyTagsToSnapshot }}',
'{{ PromotionTier }}',
'{{ EnablePerformanceInsights }}',
'{{ PerformanceInsightsKMSKeyId }}',
'{{ CACertificateIdentifier }}'
RETURNING
auto_minor_version_upgrade,
availability_zone,
backup_retention_period,
ca_certificate_identifier,
certificate_details,
copy_tags_to_snapshot,
db_cluster_identifier,
db_instance_arn,
db_instance_class,
db_instance_identifier,
db_instance_status,
db_subnet_group,
dbi_resource_id,
enabled_cloudwatch_logs_exports,
endpoint,
engine,
engine_version,
instance_create_time,
kms_key_id,
latest_restorable_time,
pending_modified_values,
performance_insights_enabled,
performance_insights_kms_key_id,
preferred_backup_window,
preferred_maintenance_window,
promotion_tier,
publicly_accessible,
status_infos,
storage_encrypted,
vpc_security_groups
;

Manifest

# Description fields are for documentation purposes
- name: db_instances
props:
  - name: DBInstanceIdentifier
    value: "{{ DBInstanceIdentifier }}"
    description: Required parameter for the db_instances resource.
  - name: DBInstanceClass
    value: "{{ DBInstanceClass }}"
    description: Required parameter for the db_instances resource.
  - name: DBClusterIdentifier
    value: "{{ DBClusterIdentifier }}"
    description: Required parameter for the db_instances resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the db_instances resource.
  - name: Engine
    value: "{{ Engine }}"
    description: The name of the database engine to be used for this instance. Valid value: docdb
    description: The name of the database engine to be used for this instance. Valid value: docdb
  - name: AvailabilityZone
    value: "{{ AvailabilityZone }}"
    description: 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
    description: 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
  - name: PreferredMaintenanceWindow
    value: "{{ PreferredMaintenanceWindow }}"
    description: 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.
    description: 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.
  - name: AutoMinorVersionUpgrade
    value: {{ AutoMinorVersionUpgrade }}
    description: This parameter does not apply to Amazon DocumentDB. Amazon DocumentDB does not perform minor version upgrades regardless of the value set. Default: false
    description: This parameter does not apply to Amazon DocumentDB. Amazon DocumentDB does not perform minor version upgrades regardless of the value set. Default: false
  - name: Tags
    value: "{{ Tags }}"
    description: The tags to be assigned to the instance. You can assign up to 10 tags to an instance.
    description: The tags to be assigned to the instance. You can assign up to 10 tags to an instance.
  - name: CopyTagsToSnapshot
    value: {{ CopyTagsToSnapshot }}
    description: A value that indicates whether to copy tags from the DB instance to snapshots of the DB instance. By default, tags are not copied.
    description: A value that indicates whether to copy tags from the DB instance to snapshots of the DB instance. By default, tags are not copied.
  - name: PromotionTier
    value: {{ PromotionTier }}
    description: 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
    description: 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
  - name: EnablePerformanceInsights
    value: {{ EnablePerformanceInsights }}
    description: A value that indicates whether to enable Performance Insights for the DB Instance. For more information, see Using Amazon Performance Insights.
    description: A value that indicates whether to enable Performance Insights for the DB Instance. For more information, see Using Amazon Performance Insights.
  - name: PerformanceInsightsKMSKeyId
    value: "{{ PerformanceInsightsKMSKeyId }}"
    description: 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.
    description: 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.
  - name: CACertificateIdentifier
    value: "{{ CACertificateIdentifier }}"
    description: 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.
    description: 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.

UPDATE examples

modify_db_instance

Modifies settings for an instance. You can change one or more database configuration parameters by specifying these parameters and the new values in the request.

UPDATE aws.docdb.db_instances
SET 
-- No updatable properties
WHERE 
DBInstanceIdentifier = '{{ DBInstanceIdentifier }}' --required
AND region = '{{ region }}' --required
AND DBInstanceClass = '{{ DBInstanceClass}}'
AND ApplyImmediately = {{ ApplyImmediately}}
AND PreferredMaintenanceWindow = '{{ PreferredMaintenanceWindow}}'
AND AutoMinorVersionUpgrade = {{ AutoMinorVersionUpgrade}}
AND NewDBInstanceIdentifier = '{{ NewDBInstanceIdentifier}}'
AND CACertificateIdentifier = '{{ CACertificateIdentifier}}'
AND CopyTagsToSnapshot = {{ CopyTagsToSnapshot}}
AND PromotionTier = '{{ PromotionTier}}'
AND EnablePerformanceInsights = {{ EnablePerformanceInsights}}
AND PerformanceInsightsKMSKeyId = '{{ PerformanceInsightsKMSKeyId}}'
AND CertificateRotationRestart = {{ CertificateRotationRestart}}
RETURNING
auto_minor_version_upgrade,
availability_zone,
backup_retention_period,
ca_certificate_identifier,
certificate_details,
copy_tags_to_snapshot,
db_cluster_identifier,
db_instance_arn,
db_instance_class,
db_instance_identifier,
db_instance_status,
db_subnet_group,
dbi_resource_id,
enabled_cloudwatch_logs_exports,
endpoint,
engine,
engine_version,
instance_create_time,
kms_key_id,
latest_restorable_time,
pending_modified_values,
performance_insights_enabled,
performance_insights_kms_key_id,
preferred_backup_window,
preferred_maintenance_window,
promotion_tier,
publicly_accessible,
status_infos,
storage_encrypted,
vpc_security_groups;

DELETE examples

delete_db_instance

Deletes a previously provisioned instance.

DELETE FROM aws.docdb.db_instances
WHERE DBInstanceIdentifier = '{{ DBInstanceIdentifier }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

reboot_db_instance

You might need to reboot your instance, usually for maintenance reasons. For example, if you make certain changes, or if you change the cluster parameter group that is associated with the instance, you must reboot the instance for the changes to take effect. Rebooting an instance restarts the database engine service. Rebooting an instance results in a momentary outage, during which the instance status is set to rebooting.

EXEC aws.docdb.db_instances.reboot_db_instance 
@DBInstanceIdentifier='{{ DBInstanceIdentifier }}' --required, 
@region='{{ region }}' --required, 
@ForceFailover={{ ForceFailover }}
;