global_clusters

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

Overview

Name	global_clusters
Type	Resource
Id	aws.neptune.global_clusters

Fields

The following fields are returned by SELECT queries:

describe_global_clusters

Name	Datatype	Description
database_name	string	The default database name within the new global database cluster.
deletion_protection	boolean	The deletion protection setting for the global database.
engine	string	The Neptune database engine used by the global database ("neptune").
engine_version	string	The Neptune engine version used by the global database.
failover_state	string	A data object containing all properties for the current state of an in-process or pending switchover or failover process for this global cluster (Neptune global database). This object is empty unless the SwitchoverGlobalCluster or FailoverGlobalCluster operation was called on this global cluster.
global_cluster_arn	string	The Amazon Resource Name (ARN) for the global database.
global_cluster_identifier	string	Contains a user-supplied global database cluster identifier. This identifier is the unique key that identifies a global database.
global_cluster_members	string	A list of cluster ARNs and instance ARNs for all the DB clusters that are part of the global database.
global_cluster_resource_id	string	An immutable identifier for the global database that is unique within all regions. This identifier is found in CloudTrail log entries whenever the KMS key for the DB cluster is accessed.
status	string	Specifies the current state of this global database.
storage_encrypted	boolean	The storage encryption setting for the global database.
tag_list	string	A list of global cluster tags.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
describe_global_clusters	select	region	GlobalClusterIdentifier, MaxRecords, Marker	Returns information about Neptune global database clusters. This API supports pagination.
create_global_cluster	insert	GlobalClusterIdentifier, region	SourceDBClusterIdentifier, Engine, EngineVersion, DeletionProtection, DatabaseName, Tags, StorageEncrypted	Creates a Neptune global database spread across multiple Amazon Regions. The global database contains a single primary cluster with read-write capability, and read-only secondary clusters that receive data from the primary cluster through high-speed replication performed by the Neptune storage subsystem. You can create a global database that is initially empty, and then add a primary cluster and secondary clusters to it, or you can specify an existing Neptune cluster during the create operation to become the primary cluster of the global database.
remove_from_global_cluster	update	GlobalClusterIdentifier, DbClusterIdentifier, region		Detaches a Neptune DB cluster from a Neptune global database. A secondary cluster becomes a normal standalone cluster with read-write capability instead of being read-only, and no longer receives data from the primary cluster.
modify_global_cluster	update	GlobalClusterIdentifier, region	NewGlobalClusterIdentifier, DeletionProtection, EngineVersion, AllowMajorVersionUpgrade	Modify a setting for an Amazon Neptune global cluster. You can change one or more database configuration parameters by specifying these parameters and their new values in the request.
delete_global_cluster	delete	GlobalClusterIdentifier, region		Deletes a global database. The primary and all secondary clusters must already be detached or deleted first.
failover_global_cluster	exec	GlobalClusterIdentifier, TargetDbClusterIdentifier, region	AllowDataLoss, Switchover	Initiates the failover process for a Neptune global database. A failover for a Neptune global database promotes one of secondary read-only DB clusters to be the primary DB cluster and demotes the primary DB cluster to being a secondary (read-only) DB cluster. In other words, the role of the current primary DB cluster and the selected target secondary DB cluster are switched. The selected secondary DB cluster assumes full read/write capabilities for the Neptune global database. This action applies only to Neptune global databases. This action is only intended for use on healthy Neptune global databases with healthy Neptune DB clusters and no region-wide outages, to test disaster recovery scenarios or to reconfigure the global database topology.
switchover_global_cluster	exec	GlobalClusterIdentifier, TargetDbClusterIdentifier, region		Switches over the specified secondary DB cluster to be the new primary DB cluster in the global database cluster. Switchover operations were previously called "managed planned failovers." Promotes the specified secondary cluster to assume full read/write capabilities and demotes the current primary cluster to a secondary (read-only) cluster, maintaining the original replication topology. All secondary clusters are synchronized with the primary at the beginning of the process so the new primary continues operations for the global database without losing any data. Your database is unavailable for a short time while the primary and selected secondary clusters are assuming their new roles. This operation is intended for controlled environments, for operations such as "regional rotation" or to fall back to the original primary after a global database failover.

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 Amazon Resource Name (ARN) identifying the cluster to be detached from the Neptune global database cluster.
GlobalClusterIdentifier	string	The identifier of the global database cluster to switch over. This parameter isn't case-sensitive. Constraints: Must match the identifier of an existing global database cluster.
TargetDbClusterIdentifier	string	The Amazon Resource Name (ARN) of the secondary Neptune DB cluster that you want to promote to primary for the global database.
region	string	AWS region (default: us-east-1)
AllowDataLoss	boolean	Specifies whether to allow data loss for this global database cluster operation. Allowing data loss triggers a global failover operation. If you don't specify AllowDataLoss, the global database cluster operation defaults to a switchover. Constraints: Can't be specified together with the Switchover parameter.
AllowMajorVersionUpgrade	boolean	A value that indicates whether major version upgrades are allowed. Constraints: You must allow major version upgrades if you specify a value for the EngineVersion parameter that is a different major version than the DB cluster's current version. If you upgrade the major version of a global database, the cluster and DB instance parameter groups are set to the default parameter groups for the new version, so you will need to apply any custom parameter groups after completing the upgrade.
DatabaseName	string	The name for the new global database (up to 64 alpha-numeric characters).
DeletionProtection	boolean	Indicates whether the global database has deletion protection enabled. The global database cannot be deleted when deletion protection is enabled.
Engine	string	The name of the database engine to be used in the global database. Valid values: neptune
EngineVersion	string	The version number of the database engine to which you want to upgrade. Changing this parameter will result in an outage. The change is applied during the next maintenance window unless ApplyImmediately is enabled. To list all of the available Neptune engine versions, use the following command:
GlobalClusterIdentifier	string	The user-supplied DB cluster identifier. If this parameter is specified, only information about the specified DB cluster is returned. This parameter is not case-sensitive. Constraints: If supplied, must match an existing DB cluster identifier.
Marker	string	(Optional) A pagination token returned by a previous call to DescribeGlobalClusters. If this parameter is specified, the response will only include records beyond the marker, up to the number 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 marker token is included in the response that you can use to retrieve the remaining results. Default: 100 Constraints: Minimum 20, maximum 100.
NewGlobalClusterIdentifier	string	A new cluster identifier to assign to the global database. 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. Can't end with a hyphen or contain two consecutive hyphens Example: my-cluster2
SourceDBClusterIdentifier	string	(Optional) The Amazon Resource Name (ARN) of an existing Neptune DB cluster to use as the primary cluster of the new global database.
StorageEncrypted	boolean	The storage encryption setting for the new global database cluster.
Switchover	boolean	Specifies whether to switch over this global database cluster. Constraints: Can't be specified together with the AllowDataLoss parameter.
Tags	array	Tags to assign to the global cluster.

SELECT examples

describe_global_clusters

Returns information about Neptune global database clusters. This API supports pagination.

SELECT
database_name,
deletion_protection,
engine,
engine_version,
failover_state,
global_cluster_arn,
global_cluster_identifier,
global_cluster_members,
global_cluster_resource_id,
status,
storage_encrypted,
tag_list
FROM aws.neptune.global_clusters
WHERE region = '{{ region }}' -- required
AND GlobalClusterIdentifier = '{{ GlobalClusterIdentifier }}'
AND MaxRecords = '{{ MaxRecords }}'
AND Marker = '{{ Marker }}'
;

INSERT examples

create_global_cluster

Creates a Neptune global database spread across multiple Amazon Regions. The global database contains a single primary cluster with read-write capability, and read-only secondary clusters that receive data from the primary cluster through high-speed replication performed by the Neptune storage subsystem. You can create a global database that is initially empty, and then add a primary cluster and secondary clusters to it, or you can specify an existing Neptune cluster during the create operation to become the primary cluster of the global database.

INSERT INTO aws.neptune.global_clusters (
GlobalClusterIdentifier,
region,
SourceDBClusterIdentifier,
Engine,
EngineVersion,
DeletionProtection,
DatabaseName,
Tags,
StorageEncrypted
)
SELECT 
'{{ GlobalClusterIdentifier }}',
'{{ region }}',
'{{ SourceDBClusterIdentifier }}',
'{{ Engine }}',
'{{ EngineVersion }}',
'{{ DeletionProtection }}',
'{{ DatabaseName }}',
'{{ Tags }}',
'{{ StorageEncrypted }}'
RETURNING
database_name,
deletion_protection,
engine,
engine_version,
failover_state,
global_cluster_arn,
global_cluster_identifier,
global_cluster_members,
global_cluster_resource_id,
status,
storage_encrypted,
tag_list
;

Manifest

# Description fields are for documentation purposes
- name: global_clusters
props:
  - name: GlobalClusterIdentifier
    value: "{{ GlobalClusterIdentifier }}"
    description: Required parameter for the global_clusters resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the global_clusters resource.
  - name: SourceDBClusterIdentifier
    value: "{{ SourceDBClusterIdentifier }}"
    description: (Optional) The Amazon Resource Name (ARN) of an existing Neptune DB cluster to use as the primary cluster of the new global database.
    description: (Optional) The Amazon Resource Name (ARN) of an existing Neptune DB cluster to use as the primary cluster of the new global database.
  - name: Engine
    value: "{{ Engine }}"
    description: The name of the database engine to be used in the global database. Valid values: neptune
    description: The name of the database engine to be used in the global database. Valid values: neptune
  - name: EngineVersion
    value: "{{ EngineVersion }}"
    description: The Neptune engine version to be used by the global database. Valid values: 1.2.0.0 or above.
    description: The Neptune engine version to be used by the global database. Valid values: 1.2.0.0 or above.
  - name: DeletionProtection
    value: {{ DeletionProtection }}
    description: The deletion protection setting for the new global database. The global database can't be deleted when deletion protection is enabled.
    description: The deletion protection setting for the new global database. The global database can't be deleted when deletion protection is enabled.
  - name: DatabaseName
    value: "{{ DatabaseName }}"
    description: The name for the new global database (up to 64 alpha-numeric characters).
    description: The name for the new global database (up to 64 alpha-numeric characters).
  - name: Tags
    value: "{{ Tags }}"
    description: Tags to assign to the global cluster.
    description: Tags to assign to the global cluster.
  - name: StorageEncrypted
    value: {{ StorageEncrypted }}
    description: The storage encryption setting for the new global database cluster.
    description: The storage encryption setting for the new global database cluster.

UPDATE examples

remove_from_global_cluster

Detaches a Neptune DB cluster from a Neptune global database. A secondary cluster becomes a normal standalone cluster with read-write capability instead of being read-only, and no longer receives data from the primary cluster.

UPDATE aws.neptune.global_clusters
SET 
-- No updatable properties
WHERE 
GlobalClusterIdentifier = '{{ GlobalClusterIdentifier }}' --required
AND DbClusterIdentifier = '{{ DbClusterIdentifier }}' --required
AND region = '{{ region }}' --required
RETURNING
database_name,
deletion_protection,
engine,
engine_version,
failover_state,
global_cluster_arn,
global_cluster_identifier,
global_cluster_members,
global_cluster_resource_id,
status,
storage_encrypted,
tag_list;

modify_global_cluster

Modify a setting for an Amazon Neptune global cluster. You can change one or more database configuration parameters by specifying these parameters and their new values in the request.

UPDATE aws.neptune.global_clusters
SET 
-- No updatable properties
WHERE 
GlobalClusterIdentifier = '{{ GlobalClusterIdentifier }}' --required
AND region = '{{ region }}' --required
AND NewGlobalClusterIdentifier = '{{ NewGlobalClusterIdentifier}}'
AND DeletionProtection = {{ DeletionProtection}}
AND EngineVersion = '{{ EngineVersion}}'
AND AllowMajorVersionUpgrade = {{ AllowMajorVersionUpgrade}}
RETURNING
database_name,
deletion_protection,
engine,
engine_version,
failover_state,
global_cluster_arn,
global_cluster_identifier,
global_cluster_members,
global_cluster_resource_id,
status,
storage_encrypted,
tag_list;

DELETE examples

delete_global_cluster

Deletes a global database. The primary and all secondary clusters must already be detached or deleted first.

DELETE FROM aws.neptune.global_clusters
WHERE GlobalClusterIdentifier = '{{ GlobalClusterIdentifier }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

failover_global_cluster

Initiates the failover process for a Neptune global database. A failover for a Neptune global database promotes one of secondary read-only DB clusters to be the primary DB cluster and demotes the primary DB cluster to being a secondary (read-only) DB cluster. In other words, the role of the current primary DB cluster and the selected target secondary DB cluster are switched. The selected secondary DB cluster assumes full read/write capabilities for the Neptune global database. This action applies only to Neptune global databases. This action is only intended for use on healthy Neptune global databases with healthy Neptune DB clusters and no region-wide outages, to test disaster recovery scenarios or to reconfigure the global database topology.

EXEC aws.neptune.global_clusters.failover_global_cluster 
@GlobalClusterIdentifier='{{ GlobalClusterIdentifier }}' --required, 
@TargetDbClusterIdentifier='{{ TargetDbClusterIdentifier }}' --required, 
@region='{{ region }}' --required, 
@AllowDataLoss={{ AllowDataLoss }}, 
@Switchover={{ Switchover }}
;

switchover_global_cluster

Switches over the specified secondary DB cluster to be the new primary DB cluster in the global database cluster. Switchover operations were previously called "managed planned failovers." Promotes the specified secondary cluster to assume full read/write capabilities and demotes the current primary cluster to a secondary (read-only) cluster, maintaining the original replication topology. All secondary clusters are synchronized with the primary at the beginning of the process so the new primary continues operations for the global database without losing any data. Your database is unavailable for a short time while the primary and selected secondary clusters are assuming their new roles. This operation is intended for controlled environments, for operations such as "regional rotation" or to fall back to the original primary after a global database failover.

EXEC aws.neptune.global_clusters.switchover_global_cluster 
@GlobalClusterIdentifier='{{ GlobalClusterIdentifier }}' --required, 
@TargetDbClusterIdentifier='{{ TargetDbClusterIdentifier }}' --required, 
@region='{{ region }}' --required
;