diff --git a/clients/client-docdb/README.md b/clients/client-docdb/README.md index 316906de7d3f..c95621bdd910 100644 --- a/clients/client-docdb/README.md +++ b/clients/client-docdb/README.md @@ -492,6 +492,14 @@ FailoverDBCluster [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/) + +
+ +FailoverGlobalCluster + + +[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/) +
diff --git a/clients/client-docdb/src/DocDB.ts b/clients/client-docdb/src/DocDB.ts index da859b0142ed..2e96c298ff38 100644 --- a/clients/client-docdb/src/DocDB.ts +++ b/clients/client-docdb/src/DocDB.ts @@ -182,6 +182,11 @@ import { FailoverDBClusterCommandInput, FailoverDBClusterCommandOutput, } from "./commands/FailoverDBClusterCommand"; +import { + FailoverGlobalClusterCommand, + FailoverGlobalClusterCommandInput, + FailoverGlobalClusterCommandOutput, +} from "./commands/FailoverGlobalClusterCommand"; import { ListTagsForResourceCommand, ListTagsForResourceCommandInput, @@ -311,6 +316,7 @@ const commands = { DescribeOrderableDBInstanceOptionsCommand, DescribePendingMaintenanceActionsCommand, FailoverDBClusterCommand, + FailoverGlobalClusterCommand, ListTagsForResourceCommand, ModifyDBClusterCommand, ModifyDBClusterParameterGroupCommand, @@ -948,6 +954,23 @@ export interface DocDB { cb: (err: any, data?: FailoverDBClusterCommandOutput) => void ): void; + /** + * @see {@link FailoverGlobalClusterCommand} + */ + failoverGlobalCluster( + args: FailoverGlobalClusterCommandInput, + options?: __HttpHandlerOptions + ): Promise; + failoverGlobalCluster( + args: FailoverGlobalClusterCommandInput, + cb: (err: any, data?: FailoverGlobalClusterCommandOutput) => void + ): void; + failoverGlobalCluster( + args: FailoverGlobalClusterCommandInput, + options: __HttpHandlerOptions, + cb: (err: any, data?: FailoverGlobalClusterCommandOutput) => void + ): void; + /** * @see {@link ListTagsForResourceCommand} */ diff --git a/clients/client-docdb/src/DocDBClient.ts b/clients/client-docdb/src/DocDBClient.ts index 6b0772078d0e..3162ec99e484 100644 --- a/clients/client-docdb/src/DocDBClient.ts +++ b/clients/client-docdb/src/DocDBClient.ts @@ -173,6 +173,10 @@ import { DescribePendingMaintenanceActionsCommandOutput, } from "./commands/DescribePendingMaintenanceActionsCommand"; import { FailoverDBClusterCommandInput, FailoverDBClusterCommandOutput } from "./commands/FailoverDBClusterCommand"; +import { + FailoverGlobalClusterCommandInput, + FailoverGlobalClusterCommandOutput, +} from "./commands/FailoverGlobalClusterCommand"; import { ListTagsForResourceCommandInput, ListTagsForResourceCommandOutput, @@ -281,6 +285,7 @@ export type ServiceInputTypes = | DescribeOrderableDBInstanceOptionsCommandInput | DescribePendingMaintenanceActionsCommandInput | FailoverDBClusterCommandInput + | FailoverGlobalClusterCommandInput | ListTagsForResourceCommandInput | ModifyDBClusterCommandInput | ModifyDBClusterParameterGroupCommandInput @@ -340,6 +345,7 @@ export type ServiceOutputTypes = | DescribeOrderableDBInstanceOptionsCommandOutput | DescribePendingMaintenanceActionsCommandOutput | FailoverDBClusterCommandOutput + | FailoverGlobalClusterCommandOutput | ListTagsForResourceCommandOutput | ModifyDBClusterCommandOutput | ModifyDBClusterParameterGroupCommandOutput diff --git a/clients/client-docdb/src/commands/FailoverGlobalClusterCommand.ts b/clients/client-docdb/src/commands/FailoverGlobalClusterCommand.ts new file mode 100644 index 000000000000..36846e22dafa --- /dev/null +++ b/clients/client-docdb/src/commands/FailoverGlobalClusterCommand.ts @@ -0,0 +1,120 @@ +// 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 { FailoverGlobalClusterMessage, FailoverGlobalClusterResult } from "../models/models_0"; +import { de_FailoverGlobalClusterCommand, se_FailoverGlobalClusterCommand } from "../protocols/Aws_query"; + +/** + * @public + */ +export type { __MetadataBearer }; +export { $Command }; +/** + * @public + * + * The input for {@link FailoverGlobalClusterCommand}. + */ +export interface FailoverGlobalClusterCommandInput extends FailoverGlobalClusterMessage {} +/** + * @public + * + * The output of {@link FailoverGlobalClusterCommand}. + */ +export interface FailoverGlobalClusterCommandOutput extends FailoverGlobalClusterResult, __MetadataBearer {} + +/** + *

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.

+ * + * @throws {@link GlobalClusterNotFoundFault} (client fault) + *

The GlobalClusterIdentifier doesn't refer to an existing global cluster.

+ * + * @throws {@link InvalidDBClusterStateFault} (client fault) + *

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-:._]* + *

+ * @public + */ + GlobalClusterIdentifier: string | undefined; + + /** + *

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-:._]* + *

+ * @public + */ + TargetDbClusterIdentifier: string | undefined; + + /** + *

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.

    + *
  • + *
+ * @public + */ + AllowDataLoss?: boolean; + + /** + *

Specifies whether to switch over this global database cluster.

+ *

Constraints:

+ *
    + *
  • + *

    Can't be specified together with the AllowDataLoss parameter.

    + *
  • + *
+ * @public + */ + Switchover?: boolean; +} + +/** + * @public + */ +export interface FailoverGlobalClusterResult { + /** + *

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 +): Promise => { + if (output.statusCode >= 300) { + return de_CommandError(output, context); + } + const data: any = await parseBody(output.body, context); + let contents: any = {}; + contents = de_FailoverGlobalClusterResult(data.FailoverGlobalClusterResult, context); + const response: FailoverGlobalClusterCommandOutput = { + $metadata: deserializeMetadata(output), + ...contents, + }; + return response; +}; + /** * deserializeAws_queryListTagsForResourceCommand */ @@ -4596,6 +4639,26 @@ const se_FailoverDBClusterMessage = (input: FailoverDBClusterMessage, context: _ return entries; }; +/** + * serializeAws_queryFailoverGlobalClusterMessage + */ +const se_FailoverGlobalClusterMessage = (input: FailoverGlobalClusterMessage, context: __SerdeContext): any => { + const entries: any = {}; + if (input[_GCI] != null) { + entries[_GCI] = input[_GCI]; + } + if (input[_TDCI] != null) { + entries[_TDCI] = input[_TDCI]; + } + if (input[_ADL] != null) { + entries[_ADL] = input[_ADL]; + } + if (input[_Sw] != null) { + entries[_Sw] = input[_Sw]; + } + return entries; +}; + /** * serializeAws_queryFilter */ @@ -6899,6 +6962,17 @@ const de_FailoverDBClusterResult = (output: any, context: __SerdeContext): Failo return contents; }; +/** + * deserializeAws_queryFailoverGlobalClusterResult + */ +const de_FailoverGlobalClusterResult = (output: any, context: __SerdeContext): FailoverGlobalClusterResult => { + const contents: any = {}; + if (output[_GC] != null) { + contents[_GC] = de_GlobalCluster(output[_GC], context); + } + return contents; +}; + /** * deserializeAws_queryGlobalCluster */ @@ -8041,6 +8115,7 @@ const _ = "2014-10-31"; const _A = "Action"; const _AA = "ApplyAction"; const _AAAD = "AutoAppliedAfterDate"; +const _ADL = "AllowDataLoss"; const _AI = "ApplyImmediately"; const _AM = "ApplyMethod"; const _AMVU = "AutoMinorVersionUpgrade"; @@ -8183,6 +8258,7 @@ const _FAD = "ForcedApplyDate"; const _FDBC = "FailoverDBCluster"; const _FDBSI = "FinalDBSnapshotIdentifier"; const _FF = "ForceFailover"; +const _FGC = "FailoverGlobalCluster"; const _GC = "GlobalCluster"; const _GCA = "GlobalClusterArn"; const _GCI = "GlobalClusterIdentifier"; @@ -8305,6 +8381,7 @@ const _STta = "StatusType"; const _St = "Status"; const _Su = "Subnets"; const _Sub = "Subnet"; +const _Sw = "Switchover"; const _T = "Tags"; const _TDBCPGD = "TargetDBClusterParameterGroupDescription"; const _TDBCPGI = "TargetDBClusterParameterGroupIdentifier"; diff --git a/codegen/sdk-codegen/aws-models/docdb.json b/codegen/sdk-codegen/aws-models/docdb.json index 68fa90598537..94e7e58a0081 100644 --- a/codegen/sdk-codegen/aws-models/docdb.json +++ b/codegen/sdk-codegen/aws-models/docdb.json @@ -245,6 +245,9 @@ { "target": "com.amazonaws.docdb#FailoverDBCluster" }, + { + "target": "com.amazonaws.docdb#FailoverGlobalCluster" + }, { "target": "com.amazonaws.docdb#ListTagsForResource" }, @@ -2812,6 +2815,16 @@ "smithy.api#httpError": 400 } }, + "com.amazonaws.docdb#DBClusterIdentifier": { + "type": "string", + "traits": { + "smithy.api#length": { + "min": 1, + "max": 255 + }, + "smithy.api#pattern": "^[A-Za-z][0-9A-Za-z-:._]*$" + } + }, "com.amazonaws.docdb#DBClusterList": { "type": "list", "member": { @@ -5763,6 +5776,79 @@ "smithy.api#output": {} } }, + "com.amazonaws.docdb#FailoverGlobalCluster": { + "type": "operation", + "input": { + "target": "com.amazonaws.docdb#FailoverGlobalClusterMessage" + }, + "output": { + "target": "com.amazonaws.docdb#FailoverGlobalClusterResult" + }, + "errors": [ + { + "target": "com.amazonaws.docdb#DBClusterNotFoundFault" + }, + { + "target": "com.amazonaws.docdb#GlobalClusterNotFoundFault" + }, + { + "target": "com.amazonaws.docdb#InvalidDBClusterStateFault" + }, + { + "target": "com.amazonaws.docdb#InvalidGlobalClusterStateFault" + } + ], + "traits": { + "smithy.api#documentation": "

Promotes the specified secondary DB cluster to be the primary DB cluster in the global cluster when failing over a global cluster occurs.

\n

Use 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.

\n

Constraints:

\n
    \n
  • \n

    Must match the identifier of an existing global cluster.

    \n
  • \n
  • \n

    Minimum length of 1. Maximum length of 255.

    \n
  • \n
\n

Pattern: [A-Za-z][0-9A-Za-z-:._]*\n

", + "smithy.api#required": {} + } + }, + "TargetDbClusterIdentifier": { + "target": "com.amazonaws.docdb#DBClusterIdentifier", + "traits": { + "smithy.api#clientOptional": {}, + "smithy.api#documentation": "

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.

\n

Constraints:

\n
    \n
  • \n

    Must match the identifier of an existing secondary cluster.

    \n
  • \n
  • \n

    Minimum length of 1. Maximum length of 255.

    \n
  • \n
\n

Pattern: [A-Za-z][0-9A-Za-z-:._]*\n

", + "smithy.api#required": {} + } + }, + "AllowDataLoss": { + "target": "com.amazonaws.docdb#BooleanOptional", + "traits": { + "smithy.api#documentation": "

Specifies whether to allow data loss for this global cluster operation. Allowing data loss triggers a global failover operation.

\n

If you don't specify AllowDataLoss, the global cluster operation defaults to a switchover.

\n

Constraints:

\n
    \n
  • \n

    Can't be specified together with the Switchover parameter.

    \n
  • \n
" + } + }, + "Switchover": { + "target": "com.amazonaws.docdb#BooleanOptional", + "traits": { + "smithy.api#documentation": "

Specifies whether to switch over this global database cluster.

\n

Constraints:

\n
    \n
  • \n

    Can't be specified together with the AllowDataLoss parameter.

    \n
  • \n
" + } + } + }, + "traits": { + "smithy.api#input": {} + } + }, + "com.amazonaws.docdb#FailoverGlobalClusterResult": { + "type": "structure", + "members": { + "GlobalCluster": { + "target": "com.amazonaws.docdb#GlobalCluster" + } + }, + "traits": { + "smithy.api#output": {} + } + }, "com.amazonaws.docdb#Filter": { "type": "structure", "members": { @@ -8441,7 +8527,7 @@ } }, "TargetDbClusterIdentifier": { - "target": "com.amazonaws.docdb#String", + "target": "com.amazonaws.docdb#DBClusterIdentifier", "traits": { "smithy.api#clientOptional": {}, "smithy.api#documentation": "

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.

\n

Constraints:

\n
    \n
  • \n

    Must match the identifier of an existing secondary cluster.

    \n
  • \n
  • \n

    Minimum length of 1. Maximum length of 255.

    \n
  • \n
\n

Pattern: [A-Za-z][0-9A-Za-z-:._]*\n

",