Skip to content

Commit 62c6973

Browse files
author
awstools
committed
feat(client-docdb): This release adds Global Cluster Failover capability which enables you to change your global cluster's primary AWS region, the region that serves writes, during a regional outage. Performing a failover action preserves your Global Cluster setup.
1 parent 2e20e95 commit 62c6973

File tree

8 files changed

+400
-1
lines changed

8 files changed

+400
-1
lines changed

‎clients/client-docdb/README.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -492,6 +492,14 @@ FailoverDBCluster
492492

493493
[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/docdb/command/FailoverDBClusterCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/FailoverDBClusterCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/FailoverDBClusterCommandOutput/)
494494

495+
</details>
496+
<details>
497+
<summary>
498+
FailoverGlobalCluster
499+
</summary>
500+
501+
[Command API Reference](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/docdb/command/FailoverGlobalClusterCommand/) / [Input](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/FailoverGlobalClusterCommandInput/) / [Output](https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/Package/-aws-sdk-client-docdb/Interface/FailoverGlobalClusterCommandOutput/)
502+
495503
</details>
496504
<details>
497505
<summary>

‎clients/client-docdb/src/DocDB.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -182,6 +182,11 @@ import {
182182
FailoverDBClusterCommandInput,
183183
FailoverDBClusterCommandOutput,
184184
} from "./commands/FailoverDBClusterCommand";
185+
import {
186+
FailoverGlobalClusterCommand,
187+
FailoverGlobalClusterCommandInput,
188+
FailoverGlobalClusterCommandOutput,
189+
} from "./commands/FailoverGlobalClusterCommand";
185190
import {
186191
ListTagsForResourceCommand,
187192
ListTagsForResourceCommandInput,
@@ -311,6 +316,7 @@ const commands = {
311316
DescribeOrderableDBInstanceOptionsCommand,
312317
DescribePendingMaintenanceActionsCommand,
313318
FailoverDBClusterCommand,
319+
FailoverGlobalClusterCommand,
314320
ListTagsForResourceCommand,
315321
ModifyDBClusterCommand,
316322
ModifyDBClusterParameterGroupCommand,
@@ -948,6 +954,23 @@ export interface DocDB {
948954
cb: (err: any, data?: FailoverDBClusterCommandOutput) => void
949955
): void;
950956

957+
/**
958+
* @see {@link FailoverGlobalClusterCommand}
959+
*/
960+
failoverGlobalCluster(
961+
args: FailoverGlobalClusterCommandInput,
962+
options?: __HttpHandlerOptions
963+
): Promise<FailoverGlobalClusterCommandOutput>;
964+
failoverGlobalCluster(
965+
args: FailoverGlobalClusterCommandInput,
966+
cb: (err: any, data?: FailoverGlobalClusterCommandOutput) => void
967+
): void;
968+
failoverGlobalCluster(
969+
args: FailoverGlobalClusterCommandInput,
970+
options: __HttpHandlerOptions,
971+
cb: (err: any, data?: FailoverGlobalClusterCommandOutput) => void
972+
): void;
973+
951974
/**
952975
* @see {@link ListTagsForResourceCommand}
953976
*/

‎clients/client-docdb/src/DocDBClient.ts‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -173,6 +173,10 @@ import {
173173
DescribePendingMaintenanceActionsCommandOutput,
174174
} from "./commands/DescribePendingMaintenanceActionsCommand";
175175
import { FailoverDBClusterCommandInput, FailoverDBClusterCommandOutput } from "./commands/FailoverDBClusterCommand";
176+
import {
177+
FailoverGlobalClusterCommandInput,
178+
FailoverGlobalClusterCommandOutput,
179+
} from "./commands/FailoverGlobalClusterCommand";
176180
import {
177181
ListTagsForResourceCommandInput,
178182
ListTagsForResourceCommandOutput,
@@ -281,6 +285,7 @@ export type ServiceInputTypes =
281285
| DescribeOrderableDBInstanceOptionsCommandInput
282286
| DescribePendingMaintenanceActionsCommandInput
283287
| FailoverDBClusterCommandInput
288+
| FailoverGlobalClusterCommandInput
284289
| ListTagsForResourceCommandInput
285290
| ModifyDBClusterCommandInput
286291
| ModifyDBClusterParameterGroupCommandInput
@@ -340,6 +345,7 @@ export type ServiceOutputTypes =
340345
| DescribeOrderableDBInstanceOptionsCommandOutput
341346
| DescribePendingMaintenanceActionsCommandOutput
342347
| FailoverDBClusterCommandOutput
348+
| FailoverGlobalClusterCommandOutput
343349
| ListTagsForResourceCommandOutput
344350
| ModifyDBClusterCommandOutput
345351
| ModifyDBClusterParameterGroupCommandOutput

‎clients/client-docdb/src/commands/FailoverGlobalClusterCommand.ts‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
// smithy-typescript generated code
2+
import { getEndpointPlugin } from "@smithy/middleware-endpoint";
3+
import { getSerdePlugin } from "@smithy/middleware-serde";
4+
import { Command as $Command } from "@smithy/smithy-client";
5+
import { MetadataBearer as __MetadataBearer } from "@smithy/types";
6+
7+
import { DocDBClientResolvedConfig, ServiceInputTypes, ServiceOutputTypes } from "../DocDBClient";
8+
import { commonParams } from "../endpoint/EndpointParameters";
9+
import { FailoverGlobalClusterMessage, FailoverGlobalClusterResult } from "../models/models_0";
10+
import { de_FailoverGlobalClusterCommand, se_FailoverGlobalClusterCommand } from "../protocols/Aws_query";
11+
12+
/**
13+
* @public
14+
*/
15+
export type { __MetadataBearer };
16+
export { $Command };
17+
/**
18+
* @public
19+
*
20+
* The input for {@link FailoverGlobalClusterCommand}.
21+
*/
22+
export interface FailoverGlobalClusterCommandInput extends FailoverGlobalClusterMessage {}
23+
/**
24+
* @public
25+
*
26+
* The output of {@link FailoverGlobalClusterCommand}.
27+
*/
28+
export interface FailoverGlobalClusterCommandOutput extends FailoverGlobalClusterResult, __MetadataBearer {}
29+
30+
/**
31+
* <p>Promotes the specified secondary DB cluster to be the primary DB cluster in the global cluster when failing over a global cluster occurs.</p>
32+
* <p>Use this operation to respond to an unplanned event, such as a regional disaster in the primary region.
33+
* Failing over can result in a loss of write transaction data that wasn't replicated to the chosen secondary before the failover event occurred.
34+
* 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.</p>
35+
* @example
36+
* Use a bare-bones client and the command you need to make an API call.
37+
* ```javascript
38+
* import { DocDBClient, FailoverGlobalClusterCommand } from "@aws-sdk/client-docdb"; // ES Modules import
39+
* // const { DocDBClient, FailoverGlobalClusterCommand } = require("@aws-sdk/client-docdb"); // CommonJS import
40+
* const client = new DocDBClient(config);
41+
* const input = { // FailoverGlobalClusterMessage
42+
* GlobalClusterIdentifier: "STRING_VALUE", // required
43+
* TargetDbClusterIdentifier: "STRING_VALUE", // required
44+
* AllowDataLoss: true || false,
45+
* Switchover: true || false,
46+
* };
47+
* const command = new FailoverGlobalClusterCommand(input);
48+
* const response = await client.send(command);
49+
* // { // FailoverGlobalClusterResult
50+
* // GlobalCluster: { // GlobalCluster
51+
* // GlobalClusterIdentifier: "STRING_VALUE",
52+
* // GlobalClusterResourceId: "STRING_VALUE",
53+
* // GlobalClusterArn: "STRING_VALUE",
54+
* // Status: "STRING_VALUE",
55+
* // Engine: "STRING_VALUE",
56+
* // EngineVersion: "STRING_VALUE",
57+
* // DatabaseName: "STRING_VALUE",
58+
* // StorageEncrypted: true || false,
59+
* // DeletionProtection: true || false,
60+
* // GlobalClusterMembers: [ // GlobalClusterMemberList
61+
* // { // GlobalClusterMember
62+
* // DBClusterArn: "STRING_VALUE",
63+
* // Readers: [ // ReadersArnList
64+
* // "STRING_VALUE",
65+
* // ],
66+
* // IsWriter: true || false,
67+
* // },
68+
* // ],
69+
* // },
70+
* // };
71+
*
72+
* ```
73+
*
74+
* @param FailoverGlobalClusterCommandInput - {@link FailoverGlobalClusterCommandInput}
75+
* @returns {@link FailoverGlobalClusterCommandOutput}
76+
* @see {@link FailoverGlobalClusterCommandInput} for command's `input` shape.
77+
* @see {@link FailoverGlobalClusterCommandOutput} for command's `response` shape.
78+
* @see {@link DocDBClientResolvedConfig | config} for DocDBClient's `config` shape.
79+
*
80+
* @throws {@link DBClusterNotFoundFault} (client fault)
81+
* <p>
82+
* <code>DBClusterIdentifier</code> doesn't refer to an existing cluster. </p>
83+
*
84+
* @throws {@link GlobalClusterNotFoundFault} (client fault)
85+
* <p>The <code>GlobalClusterIdentifier</code> doesn't refer to an existing global cluster.</p>
86+
*
87+
* @throws {@link InvalidDBClusterStateFault} (client fault)
88+
* <p>The cluster isn't in a valid state.</p>
89+
*
90+
* @throws {@link InvalidGlobalClusterStateFault} (client fault)
91+
* <p>The requested operation can't be performed while the cluster is in this state.</p>
92+
*
93+
* @throws {@link DocDBServiceException}
94+
* <p>Base exception class for all service exceptions from DocDB service.</p>
95+
*
96+
* @public
97+
*/
98+
export class FailoverGlobalClusterCommand extends $Command
99+
.classBuilder<
100+
FailoverGlobalClusterCommandInput,
101+
FailoverGlobalClusterCommandOutput,
102+
DocDBClientResolvedConfig,
103+
ServiceInputTypes,
104+
ServiceOutputTypes
105+
>()
106+
.ep({
107+
...commonParams,
108+
})
109+
.m(function (this: any, Command: any, cs: any, config: DocDBClientResolvedConfig, o: any) {
110+
return [
111+
getSerdePlugin(config, this.serialize, this.deserialize),
112+
getEndpointPlugin(config, Command.getEndpointParameterInstructions()),
113+
];
114+
})
115+
.s("AmazonRDSv19", "FailoverGlobalCluster", {})
116+
.n("DocDBClient", "FailoverGlobalClusterCommand")
117+
.f(void 0, void 0)
118+
.ser(se_FailoverGlobalClusterCommand)
119+
.de(de_FailoverGlobalClusterCommand)
120+
.build() {}

‎clients/client-docdb/src/commands/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ export * from "./DescribeGlobalClustersCommand";
3535
export * from "./DescribeOrderableDBInstanceOptionsCommand";
3636
export * from "./DescribePendingMaintenanceActionsCommand";
3737
export * from "./FailoverDBClusterCommand";
38+
export * from "./FailoverGlobalClusterCommand";
3839
export * from "./ListTagsForResourceCommand";
3940
export * from "./ModifyDBClusterCommand";
4041
export * from "./ModifyDBClusterParameterGroupCommand";

‎clients/client-docdb/src/models/models_0.ts‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5041,6 +5041,84 @@ export interface FailoverDBClusterResult {
50415041
DBCluster?: DBCluster;
50425042
}
50435043

5044+
/**
5045+
* @public
5046+
*/
5047+
export interface FailoverGlobalClusterMessage {
5048+
/**
5049+
* <p>The identifier of the Amazon DocumentDB global cluster to apply this operation.
5050+
* The identifier is the unique key assigned by the user when the cluster is created.
5051+
* In other words, it's the name of the global cluster.</p>
5052+
* <p>Constraints:</p>
5053+
* <ul>
5054+
* <li>
5055+
* <p>Must match the identifier of an existing global cluster.</p>
5056+
* </li>
5057+
* <li>
5058+
* <p>Minimum length of 1. Maximum length of 255.</p>
5059+
* </li>
5060+
* </ul>
5061+
* <p>Pattern: <code>[A-Za-z][0-9A-Za-z-:._]*</code>
5062+
* </p>
5063+
* @public
5064+
*/
5065+
GlobalClusterIdentifier: string | undefined;
5066+
5067+
/**
5068+
* <p>The identifier of the secondary Amazon DocumentDB cluster that you want to promote to the primary for the global cluster.
5069+
* Use the Amazon Resource Name (ARN) for the identifier so that Amazon DocumentDB can locate the cluster in its Amazon Web Services region.</p>
5070+
* <p>Constraints:</p>
5071+
* <ul>
5072+
* <li>
5073+
* <p>Must match the identifier of an existing secondary cluster.</p>
5074+
* </li>
5075+
* <li>
5076+
* <p>Minimum length of 1. Maximum length of 255.</p>
5077+
* </li>
5078+
* </ul>
5079+
* <p>Pattern: <code>[A-Za-z][0-9A-Za-z-:._]*</code>
5080+
* </p>
5081+
* @public
5082+
*/
5083+
TargetDbClusterIdentifier: string | undefined;
5084+
5085+
/**
5086+
* <p>Specifies whether to allow data loss for this global cluster operation. Allowing data loss triggers a global failover operation.</p>
5087+
* <p>If you don't specify <code>AllowDataLoss</code>, the global cluster operation defaults to a switchover.</p>
5088+
* <p>Constraints:</p>
5089+
* <ul>
5090+
* <li>
5091+
* <p>Can't be specified together with the <code>Switchover</code> parameter.</p>
5092+
* </li>
5093+
* </ul>
5094+
* @public
5095+
*/
5096+
AllowDataLoss?: boolean;
5097+
5098+
/**
5099+
* <p>Specifies whether to switch over this global database cluster.</p>
5100+
* <p>Constraints:</p>
5101+
* <ul>
5102+
* <li>
5103+
* <p>Can't be specified together with the <code>AllowDataLoss</code> parameter.</p>
5104+
* </li>
5105+
* </ul>
5106+
* @public
5107+
*/
5108+
Switchover?: boolean;
5109+
}
5110+
5111+
/**
5112+
* @public
5113+
*/
5114+
export interface FailoverGlobalClusterResult {
5115+
/**
5116+
* <p>A data type representing an Amazon DocumentDB global cluster.</p>
5117+
* @public
5118+
*/
5119+
GlobalCluster?: GlobalCluster;
5120+
}
5121+
50445122
/**
50455123
* <p>Represents the input to <a>ListTagsForResource</a>.</p>
50465124
* @public

0 commit comments

Comments
 (0)