feat(client-docdb): This release adds Global Cluster Switchover capability which enables you to change your global cluster's primary AWS Region, the region that serves writes, while preserving the replication between all regions in the global cluster.

awstools · awstools · commit b7817fd7f631 · 2024-04-03T18:16:21.000Z
diff --git a/clients/client-docdb/README.md b/clients/client-docdb/README.md
@@ -629,3 +629,11 @@ StopDBCluster
 [Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/docdb/command/StopDBClusterCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/StopDBClusterCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/StopDBClusterCommandOutput/)
 
 </details>
+<details>
+<summary>
+SwitchoverGlobalCluster
+</summary>
+
+[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/docdb/command/SwitchoverGlobalClusterCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/SwitchoverGlobalClusterCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/SwitchoverGlobalClusterCommandOutput/)
+
+</details>
diff --git a/clients/client-docdb/src/DocDB.ts b/clients/client-docdb/src/DocDB.ts
@@ -267,6 +267,11 @@ import {
   StopDBClusterCommandInput,
   StopDBClusterCommandOutput,
 } from "./commands/StopDBClusterCommand";
+import {
+  SwitchoverGlobalClusterCommand,
+  SwitchoverGlobalClusterCommandInput,
+  SwitchoverGlobalClusterCommandOutput,
+} from "./commands/SwitchoverGlobalClusterCommand";
 import { DocDBClient, DocDBClientConfig } from "./DocDBClient";
 
 const commands = {
@@ -323,6 +328,7 @@ const commands = {
   RestoreDBClusterToPointInTimeCommand,
   StartDBClusterCommand,
   StopDBClusterCommand,
+  SwitchoverGlobalClusterCommand,
 };
 
 export interface DocDB {
@@ -1218,6 +1224,23 @@ export interface DocDB {
     options: __HttpHandlerOptions,
     cb: (err: any, data?: StopDBClusterCommandOutput) => void
   ): void;
+
+  /**
+   * @see {@link SwitchoverGlobalClusterCommand}
+   */
+  switchoverGlobalCluster(
+    args: SwitchoverGlobalClusterCommandInput,
+    options?: __HttpHandlerOptions
+  ): Promise<SwitchoverGlobalClusterCommandOutput>;
+  switchoverGlobalCluster(
+    args: SwitchoverGlobalClusterCommandInput,
+    cb: (err: any, data?: SwitchoverGlobalClusterCommandOutput) => void
+  ): void;
+  switchoverGlobalCluster(
+    args: SwitchoverGlobalClusterCommandInput,
+    options: __HttpHandlerOptions,
+    cb: (err: any, data?: SwitchoverGlobalClusterCommandOutput) => void
+  ): void;
 }
 
 /**
diff --git a/clients/client-docdb/src/DocDBClient.ts b/clients/client-docdb/src/DocDBClient.ts
@@ -226,6 +226,10 @@ import {
 } from "./commands/RestoreDBClusterToPointInTimeCommand";
 import { StartDBClusterCommandInput, StartDBClusterCommandOutput } from "./commands/StartDBClusterCommand";
 import { StopDBClusterCommandInput, StopDBClusterCommandOutput } from "./commands/StopDBClusterCommand";
+import {
+  SwitchoverGlobalClusterCommandInput,
+  SwitchoverGlobalClusterCommandOutput,
+} from "./commands/SwitchoverGlobalClusterCommand";
 import {
   ClientInputEndpointParameters,
   ClientResolvedEndpointParameters,
@@ -293,7 +297,8 @@ export type ServiceInputTypes =
   | RestoreDBClusterFromSnapshotCommandInput
   | RestoreDBClusterToPointInTimeCommandInput
   | StartDBClusterCommandInput
-  | StopDBClusterCommandInput;
+  | StopDBClusterCommandInput
+  | SwitchoverGlobalClusterCommandInput;
 
 /**
  * @public
@@ -351,7 +356,8 @@ export type ServiceOutputTypes =
   | RestoreDBClusterFromSnapshotCommandOutput
   | RestoreDBClusterToPointInTimeCommandOutput
   | StartDBClusterCommandOutput
-  | StopDBClusterCommandOutput;
+  | StopDBClusterCommandOutput
+  | SwitchoverGlobalClusterCommandOutput;
 
 /**
  * @public
diff --git a/clients/client-docdb/src/commands/SwitchoverGlobalClusterCommand.ts b/clients/client-docdb/src/commands/SwitchoverGlobalClusterCommand.ts
@@ -0,0 +1,114 @@
+// smithy-typescript generated code
+import { getEndpointPlugin } from "@smithy/middleware-endpoint";
+import { getSerdePlugin } from "@smithy/middleware-serde";
+import { Command as $Command } from "@smithy/smithy-client";
+import { MetadataBearer as __MetadataBearer } from "@smithy/types";
+
+import { DocDBClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../DocDBClient";
+import { commonParams } from "../endpoint/EndpointParameters";
+import { SwitchoverGlobalClusterMessage, SwitchoverGlobalClusterResult } from "../models/models_0";
+import { de_SwitchoverGlobalClusterCommand, se_SwitchoverGlobalClusterCommand } from "../protocols/Aws_query";
+
+/**
+ * @public
+ */
+export { __MetadataBearer, $Command };
+/**
+ * @public
+ *
+ * The input for {@link SwitchoverGlobalClusterCommand}.
+ */
+export interface SwitchoverGlobalClusterCommandInput extends SwitchoverGlobalClusterMessage {}
+/**
+ * @public
+ *
+ * The output of {@link SwitchoverGlobalClusterCommand}.
+ */
+export interface SwitchoverGlobalClusterCommandOutput extends SwitchoverGlobalClusterResult, __MetadataBearer {}
+
+/**
+ * <p>Switches over the specified secondary Amazon DocumentDB cluster to be the new primary Amazon DocumentDB cluster in the global database cluster.</p>
+ * @example
+ * Use a bare-bones client and the command you need to make an API call.
+ * ```javascript
+ * import { DocDBClient, SwitchoverGlobalClusterCommand } from "@aws-sdk/client-docdb"; // ES Modules import
+ * // const { DocDBClient, SwitchoverGlobalClusterCommand } = require("@aws-sdk/client-docdb"); // CommonJS import
+ * const client = new DocDBClient(config);
+ * const input = { // SwitchoverGlobalClusterMessage
+ *   GlobalClusterIdentifier: "STRING_VALUE", // required
+ *   TargetDbClusterIdentifier: "STRING_VALUE", // required
+ * };
+ * const command = new SwitchoverGlobalClusterCommand(input);
+ * const response = await client.send(command);
+ * // { // SwitchoverGlobalClusterResult
+ * //   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 SwitchoverGlobalClusterCommandInput - {@link SwitchoverGlobalClusterCommandInput}
+ * @returns {@link SwitchoverGlobalClusterCommandOutput}
+ * @see {@link SwitchoverGlobalClusterCommandInput} for command's `input` shape.
+ * @see {@link SwitchoverGlobalClusterCommandOutput} for command's `response` shape.
+ * @see {@link DocDBClientResolvedConfig | config} for DocDBClient's `config` shape.
+ *
+ * @throws {@link DBClusterNotFoundFault} (client fault)
+ *  <p>
+ *             <code>DBClusterIdentifier</code> doesn't refer to an existing cluster. </p>
+ *
+ * @throws {@link GlobalClusterNotFoundFault} (client fault)
+ *  <p>The <code>GlobalClusterIdentifier</code> doesn't refer to an existing global cluster.</p>
+ *
+ * @throws {@link InvalidDBClusterStateFault} (client fault)
+ *  <p>The cluster isn't in a valid state.</p>
+ *
+ * @throws {@link InvalidGlobalClusterStateFault} (client fault)
+ *  <p>The requested operation can't be performed while the cluster is in this state.</p>
+ *
+ * @throws {@link DocDBServiceException}
+ * <p>Base exception class for all service exceptions from DocDB service.</p>
+ *
+ * @public
+ */
+export class SwitchoverGlobalClusterCommand extends $Command
+  .classBuilder<
+    SwitchoverGlobalClusterCommandInput,
+    SwitchoverGlobalClusterCommandOutput,
+    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", "SwitchoverGlobalCluster", {})
+  .n("DocDBClient", "SwitchoverGlobalClusterCommand")
+  .f(void 0, void 0)
+  .ser(se_SwitchoverGlobalClusterCommand)
+  .de(de_SwitchoverGlobalClusterCommand)
+  .build() {}
diff --git a/clients/client-docdb/src/commands/index.ts b/clients/client-docdb/src/commands/index.ts
@@ -52,3 +52,4 @@ export * from "./RestoreDBClusterFromSnapshotCommand";
 export * from "./RestoreDBClusterToPointInTimeCommand";
 export * from "./StartDBClusterCommand";
 export * from "./StopDBClusterCommand";
+export * from "./SwitchoverGlobalClusterCommand";
diff --git a/clients/client-docdb/src/models/models_0.ts b/clients/client-docdb/src/models/models_0.ts
@@ -6351,3 +6351,57 @@ export interface StopDBClusterResult {
    */
   DBCluster?: DBCluster;
 }
+
+/**
+ * @public
+ */
+export interface SwitchoverGlobalClusterMessage {
+  /**
+   * <p>The identifier of the Amazon DocumentDB global database cluster to switch over.
+   *         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.
+   *         This parameter isn’t case-sensitive.</p>
+   *          <p>Constraints:</p>
+   *          <ul>
+   *             <li>
+   *                <p>Must match the identifier of an existing global cluster (Amazon DocumentDB global database).</p>
+   *             </li>
+   *             <li>
+   *                <p>Minimum length of 1. Maximum length of 255.</p>
+   *             </li>
+   *          </ul>
+   *          <p>Pattern: <code>[A-Za-z][0-9A-Za-z-:._]*</code>
+   *          </p>
+   * @public
+   */
+  GlobalClusterIdentifier: string | undefined;
+
+  /**
+   * <p>The identifier of the secondary Amazon DocumentDB cluster to promote to the new primary for the global database cluster.
+   *             Use the Amazon Resource Name (ARN) for the identifier so that Amazon DocumentDB can locate the cluster in its Amazon Web Services region.</p>
+   *          <p>Constraints:</p>
+   *          <ul>
+   *             <li>
+   *                <p>Must match the identifier of an existing secondary cluster.</p>
+   *             </li>
+   *             <li>
+   *                <p>Minimum length of 1. Maximum length of 255.</p>
+   *             </li>
+   *          </ul>
+   *          <p>Pattern: <code>[A-Za-z][0-9A-Za-z-:._]*</code>
+   *          </p>
+   * @public
+   */
+  TargetDbClusterIdentifier: string | undefined;
+}
+
+/**
+ * @public
+ */
+export interface SwitchoverGlobalClusterResult {
+  /**
+   * <p>A data type representing an Amazon DocumentDB global cluster.</p>
+   * @public
+   */
+  GlobalCluster?: GlobalCluster;
+}
diff --git a/clients/client-docdb/src/protocols/Aws_query.ts b/clients/client-docdb/src/protocols/Aws_query.ts
@@ -193,6 +193,10 @@ import {
 } from "../commands/RestoreDBClusterToPointInTimeCommand";
 import { StartDBClusterCommandInput, StartDBClusterCommandOutput } from "../commands/StartDBClusterCommand";
 import { StopDBClusterCommandInput, StopDBClusterCommandOutput } from "../commands/StopDBClusterCommand";
+import {
+  SwitchoverGlobalClusterCommandInput,
+  SwitchoverGlobalClusterCommandOutput,
+} from "../commands/SwitchoverGlobalClusterCommand";
 import { DocDBServiceException as __BaseException } from "../models/DocDBServiceException";
 import {
   AddSourceIdentifierToSubscriptionMessage,
@@ -382,6 +386,8 @@ import {
   SubscriptionAlreadyExistFault,
   SubscriptionCategoryNotFoundFault,
   SubscriptionNotFoundFault,
+  SwitchoverGlobalClusterMessage,
+  SwitchoverGlobalClusterResult,
   Tag,
   TagListMessage,
   UpgradeTarget,
@@ -1289,6 +1295,23 @@ export const se_StopDBClusterCommand = async (
   return buildHttpRpcRequest(context, headers, "/", undefined, body);
 };
 
+/**
+ * serializeAws_querySwitchoverGlobalClusterCommand
+ */
+export const se_SwitchoverGlobalClusterCommand = async (
+  input: SwitchoverGlobalClusterCommandInput,
+  context: __SerdeContext
+): Promise<__HttpRequest> => {
+  const headers: __HeaderBag = SHARED_HEADERS;
+  let body: any;
+  body = buildFormUrlencodedString({
+    ...se_SwitchoverGlobalClusterMessage(input, context),
+    [_A]: _SGC,
+    [_V]: _,
+  });
+  return buildHttpRpcRequest(context, headers, "/", undefined, body);
+};
+
 /**
  * deserializeAws_queryAddSourceIdentifierToSubscriptionCommand
  */
@@ -2343,6 +2366,26 @@ export const de_StopDBClusterCommand = async (
   return response;
 };
 
+/**
+ * deserializeAws_querySwitchoverGlobalClusterCommand
+ */
+export const de_SwitchoverGlobalClusterCommand = async (
+  output: __HttpResponse,
+  context: __SerdeContext
+): Promise<SwitchoverGlobalClusterCommandOutput> => {
+  if (output.statusCode >= 300) {
+    return de_CommandError(output, context);
+  }
+  const data: any = await parseBody(output.body, context);
+  let contents: any = {};
+  contents = de_SwitchoverGlobalClusterResult(data.SwitchoverGlobalClusterResult, context);
+  const response: SwitchoverGlobalClusterCommandOutput = {
+    $metadata: deserializeMetadata(output),
+    ...contents,
+  };
+  return response;
+};
+
 /**
  * deserialize_Aws_queryCommandError
  */
@@ -5257,6 +5300,20 @@ const se_SubnetIdentifierList = (input: string[], context: __SerdeContext): any
   return entries;
 };
 
+/**
+ * serializeAws_querySwitchoverGlobalClusterMessage
+ */
+const se_SwitchoverGlobalClusterMessage = (input: SwitchoverGlobalClusterMessage, context: __SerdeContext): any => {
+  const entries: any = {};
+  if (input[_GCI] != null) {
+    entries[_GCI] = input[_GCI];
+  }
+  if (input[_TDCI] != null) {
+    entries[_TDCI] = input[_TDCI];
+  }
+  return entries;
+};
+
 /**
  * serializeAws_queryTag
  */
@@ -7830,6 +7887,17 @@ const de_SubscriptionNotFoundFault = (output: any, context: __SerdeContext): Sub
   return contents;
 };
 
+/**
+ * deserializeAws_querySwitchoverGlobalClusterResult
+ */
+const de_SwitchoverGlobalClusterResult = (output: any, context: __SerdeContext): SwitchoverGlobalClusterResult => {
+  const contents: any = {};
+  if (output[_GC] != null) {
+    contents[_GC] = de_GlobalCluster(output[_GC], context);
+  }
+  return contents;
+};
+
 /**
  * deserializeAws_queryTag
  */
@@ -8214,6 +8282,7 @@ const _SDBCSI = "SourceDBClusterSnapshotIdentifier";
 const _SDBCt = "StopDBCluster";
 const _SE = "StorageEncrypted";
 const _SFS = "SkipFinalSnapshot";
+const _SGC = "SwitchoverGlobalCluster";
 const _SGS = "SubnetGroupStatus";
 const _SI = "SourceIdentifier";
 const _SIL = "SourceIdsList";
@@ -8240,6 +8309,7 @@ const _TDBCPGD = "TargetDBClusterParameterGroupDescription";
 const _TDBCPGI = "TargetDBClusterParameterGroupIdentifier";
 const _TDBCSI = "TargetDBClusterSnapshotIdentifier";
 const _TDBII = "TargetDBInstanceIdentifier";
+const _TDCI = "TargetDbClusterIdentifier";
 const _TK = "TagKeys";
 const _TL = "TagList";
 const _Ta = "Tag";
diff --git a/codegen/sdk-codegen/aws-models/docdb.json b/codegen/sdk-codegen/aws-models/docdb.json
