Promotes the specified secondary DB cluster to be the primary DB cluster in the global cluster when failing over a global cluster occurs.
+ *Use this operation to respond to an unplanned event, such as a regional disaster in the primary region. + * Failing over can result in a loss of write transaction data that wasn't replicated to the chosen secondary before the failover event occurred. + * However, the recovery process that promotes a DB instance on the chosen seconday DB cluster to be the primary writer DB instance guarantees that the data is in a transactionally consistent state.
+ * @example + * Use a bare-bones client and the command you need to make an API call. + * ```javascript + * import { DocDBClient, FailoverGlobalClusterCommand } from "@aws-sdk/client-docdb"; // ES Modules import + * // const { DocDBClient, FailoverGlobalClusterCommand } = require("@aws-sdk/client-docdb"); // CommonJS import + * const client = new DocDBClient(config); + * const input = { // FailoverGlobalClusterMessage + * GlobalClusterIdentifier: "STRING_VALUE", // required + * TargetDbClusterIdentifier: "STRING_VALUE", // required + * AllowDataLoss: true || false, + * Switchover: true || false, + * }; + * const command = new FailoverGlobalClusterCommand(input); + * const response = await client.send(command); + * // { // FailoverGlobalClusterResult + * // GlobalCluster: { // GlobalCluster + * // GlobalClusterIdentifier: "STRING_VALUE", + * // GlobalClusterResourceId: "STRING_VALUE", + * // GlobalClusterArn: "STRING_VALUE", + * // Status: "STRING_VALUE", + * // Engine: "STRING_VALUE", + * // EngineVersion: "STRING_VALUE", + * // DatabaseName: "STRING_VALUE", + * // StorageEncrypted: true || false, + * // DeletionProtection: true || false, + * // GlobalClusterMembers: [ // GlobalClusterMemberList + * // { // GlobalClusterMember + * // DBClusterArn: "STRING_VALUE", + * // Readers: [ // ReadersArnList + * // "STRING_VALUE", + * // ], + * // IsWriter: true || false, + * // }, + * // ], + * // }, + * // }; + * + * ``` + * + * @param FailoverGlobalClusterCommandInput - {@link FailoverGlobalClusterCommandInput} + * @returns {@link FailoverGlobalClusterCommandOutput} + * @see {@link FailoverGlobalClusterCommandInput} for command's `input` shape. + * @see {@link FailoverGlobalClusterCommandOutput} for command's `response` shape. + * @see {@link DocDBClientResolvedConfig | config} for DocDBClient's `config` shape. + * + * @throws {@link DBClusterNotFoundFault} (client fault) + *
+ * DBClusterIdentifier
doesn't refer to an existing cluster.
The GlobalClusterIdentifier
doesn't refer to an existing global cluster.
The cluster isn't in a valid state.
+ * + * @throws {@link InvalidGlobalClusterStateFault} (client fault) + *The requested operation can't be performed while the cluster is in this state.
+ * + * @throws {@link DocDBServiceException} + *Base exception class for all service exceptions from DocDB service.
+ * + * @public + */ +export class FailoverGlobalClusterCommand extends $Command + .classBuilder< + FailoverGlobalClusterCommandInput, + FailoverGlobalClusterCommandOutput, + DocDBClientResolvedConfig, + ServiceInputTypes, + ServiceOutputTypes + >() + .ep({ + ...commonParams, + }) + .m(function (this: any, Command: any, cs: any, config: DocDBClientResolvedConfig, o: any) { + return [ + getSerdePlugin(config, this.serialize, this.deserialize), + getEndpointPlugin(config, Command.getEndpointParameterInstructions()), + ]; + }) + .s("AmazonRDSv19", "FailoverGlobalCluster", {}) + .n("DocDBClient", "FailoverGlobalClusterCommand") + .f(void 0, void 0) + .ser(se_FailoverGlobalClusterCommand) + .de(de_FailoverGlobalClusterCommand) + .build() {} diff --git a/clients/client-docdb/src/commands/index.ts b/clients/client-docdb/src/commands/index.ts index 2ca263b6e8e5..cc18a32e36b6 100644 --- a/clients/client-docdb/src/commands/index.ts +++ b/clients/client-docdb/src/commands/index.ts @@ -35,6 +35,7 @@ export * from "./DescribeGlobalClustersCommand"; export * from "./DescribeOrderableDBInstanceOptionsCommand"; export * from "./DescribePendingMaintenanceActionsCommand"; export * from "./FailoverDBClusterCommand"; +export * from "./FailoverGlobalClusterCommand"; export * from "./ListTagsForResourceCommand"; export * from "./ModifyDBClusterCommand"; export * from "./ModifyDBClusterParameterGroupCommand"; diff --git a/clients/client-docdb/src/models/models_0.ts b/clients/client-docdb/src/models/models_0.ts index 4b55f9cb94d9..963ffcc710bf 100644 --- a/clients/client-docdb/src/models/models_0.ts +++ b/clients/client-docdb/src/models/models_0.ts @@ -5041,6 +5041,84 @@ export interface FailoverDBClusterResult { DBCluster?: DBCluster; } +/** + * @public + */ +export interface FailoverGlobalClusterMessage { + /** + *The identifier of the Amazon DocumentDB global cluster to apply this operation. + * The identifier is the unique key assigned by the user when the cluster is created. + * In other words, it's the name of the global cluster.
+ *Constraints:
+ *Must match the identifier of an existing global cluster.
+ *Minimum length of 1. Maximum length of 255.
+ *Pattern: [A-Za-z][0-9A-Za-z-:._]*
+ *
The identifier of the secondary Amazon DocumentDB cluster that you want to promote to the primary for the global cluster. + * Use the Amazon Resource Name (ARN) for the identifier so that Amazon DocumentDB can locate the cluster in its Amazon Web Services region.
+ *Constraints:
+ *Must match the identifier of an existing secondary cluster.
+ *Minimum length of 1. Maximum length of 255.
+ *Pattern: [A-Za-z][0-9A-Za-z-:._]*
+ *
Specifies whether to allow data loss for this global cluster operation. Allowing data loss triggers a global failover operation.
+ *If you don't specify AllowDataLoss
, the global cluster operation defaults to a switchover.
Constraints:
+ *Can't be specified together with the Switchover
parameter.
Specifies whether to switch over this global database cluster.
+ *Constraints:
+ *Can't be specified together with the AllowDataLoss
parameter.
A data type representing an Amazon DocumentDB global cluster.
+ * @public + */ + GlobalCluster?: GlobalCluster; +} + /** *Represents the input to ListTagsForResource.
* @public diff --git a/clients/client-docdb/src/protocols/Aws_query.ts b/clients/client-docdb/src/protocols/Aws_query.ts index 0df969084a10..d7960abfa9e0 100644 --- a/clients/client-docdb/src/protocols/Aws_query.ts +++ b/clients/client-docdb/src/protocols/Aws_query.ts @@ -141,6 +141,10 @@ import { DescribePendingMaintenanceActionsCommandOutput, } from "../commands/DescribePendingMaintenanceActionsCommand"; import { FailoverDBClusterCommandInput, FailoverDBClusterCommandOutput } from "../commands/FailoverDBClusterCommand"; +import { + FailoverGlobalClusterCommandInput, + FailoverGlobalClusterCommandOutput, +} from "../commands/FailoverGlobalClusterCommand"; import { ListTagsForResourceCommandInput, ListTagsForResourceCommandOutput, @@ -310,6 +314,8 @@ import { EventSubscriptionsMessage, FailoverDBClusterMessage, FailoverDBClusterResult, + FailoverGlobalClusterMessage, + FailoverGlobalClusterResult, Filter, GlobalCluster, GlobalClusterAlreadyExistsFault, @@ -1007,6 +1013,23 @@ export const se_FailoverDBClusterCommand = async ( return buildHttpRpcRequest(context, headers, "/", undefined, body); }; +/** + * serializeAws_queryFailoverGlobalClusterCommand + */ +export const se_FailoverGlobalClusterCommand = async ( + input: FailoverGlobalClusterCommandInput, + context: __SerdeContext +): Promise<__HttpRequest> => { + const headers: __HeaderBag = SHARED_HEADERS; + let body: any; + body = buildFormUrlencodedString({ + ...se_FailoverGlobalClusterMessage(input, context), + [_A]: _FGC, + [_V]: _, + }); + return buildHttpRpcRequest(context, headers, "/", undefined, body); +}; + /** * serializeAws_queryListTagsForResourceCommand */ @@ -2027,6 +2050,26 @@ export const de_FailoverDBClusterCommand = async ( return response; }; +/** + * deserializeAws_queryFailoverGlobalClusterCommand + */ +export const de_FailoverGlobalClusterCommand = async ( + output: __HttpResponse, + context: __SerdeContext +): PromisePromotes the specified secondary DB cluster to be the primary DB cluster in the global cluster when failing over a global cluster occurs.
\nUse this operation to respond to an unplanned event, such as a regional disaster in the primary region. \n Failing over can result in a loss of write transaction data that wasn't replicated to the chosen secondary before the failover event occurred. \n However, the recovery process that promotes a DB instance on the chosen seconday DB cluster to be the primary writer DB instance guarantees that the data is in a transactionally consistent state.
" + } + }, + "com.amazonaws.docdb#FailoverGlobalClusterMessage": { + "type": "structure", + "members": { + "GlobalClusterIdentifier": { + "target": "com.amazonaws.docdb#GlobalClusterIdentifier", + "traits": { + "smithy.api#clientOptional": {}, + "smithy.api#documentation": "The identifier of the Amazon DocumentDB global cluster to apply this operation. \n The identifier is the unique key assigned by the user when the cluster is created. \n In other words, it's the name of the global cluster.
\nConstraints:
\nMust match the identifier of an existing global cluster.
\nMinimum length of 1. Maximum length of 255.
\nPattern: [A-Za-z][0-9A-Za-z-:._]*
\n
The identifier of the secondary Amazon DocumentDB cluster that you want to promote to the primary for the global cluster. \n Use the Amazon Resource Name (ARN) for the identifier so that Amazon DocumentDB can locate the cluster in its Amazon Web Services region.
\nConstraints:
\nMust match the identifier of an existing secondary cluster.
\nMinimum length of 1. Maximum length of 255.
\nPattern: [A-Za-z][0-9A-Za-z-:._]*
\n
Specifies whether to allow data loss for this global cluster operation. Allowing data loss triggers a global failover operation.
\nIf you don't specify AllowDataLoss
, the global cluster operation defaults to a switchover.
Constraints:
\nCan't be specified together with the Switchover
parameter.
Specifies whether to switch over this global database cluster.
\nConstraints:
\nCan't be specified together with the AllowDataLoss
parameter.
The identifier of the secondary Amazon DocumentDB cluster to promote to the new primary for the global database cluster. \n Use the Amazon Resource Name (ARN) for the identifier so that Amazon DocumentDB can locate the cluster in its Amazon Web Services region.
\nConstraints:
\nMust match the identifier of an existing secondary cluster.
\nMinimum length of 1. Maximum length of 255.
\nPattern: [A-Za-z][0-9A-Za-z-:._]*
\n