aws-dynamodb: TableV2 should be called GlobalTable

[christophercurrie]

Describe the feature

The TableV2 construct should be named GlobalTable to provide a clear mapping to the underlying CloudFormation construct and avoid customer confusion around why it behaves differently.

Use Case

The construct is confusingly named, and breaks customer expectations. Based on the name, one would have reason to expect it to create a AWS::DynamoDB::Table resource, when it creates AWS::DynamoDB::GlobalTable resources. This is especially confusing because it is not mentioned at all in the documentation for the construct.

This has already caused customer confusion, as reported in #27378 and #27443. The answers to those issues did not help clarify the situation, as both answers simply reported that the CDK construct didn't support the desired behavior, but failed to fully explain why. The only mention of the difference is in a blog post.

Proposed Solution

• Rename TableV2 to GlobalTable.
• Create a new TableV2 that forwards to GlobalTable and is marked deprecated, to prompt customers to use the new name.

Other Information

No response

Acknowledgements

• I may be able to implement this feature request
• This feature might incur a breaking change

CDK version used

2.87.0

Environment details (OS name and version, etc.)

macOS 14.3

[arjanschaaf]

I would recommend not changing it to GlobalTable because it should be a best practice to use the underlying AWS::DynamoDB::GlobalTable for any table, including tables that only need to support 1 region. Using AWS::DynamoDB::GlobalTable / TableV2 allows an upgrade path toward adding additional regions easily. If the CDK construct would be called GlobalTable CDK users might use the older Table construct. Which would be undesirable because it would make it much more complicated to migrate to the TableV2 / GlobalTable construct at a later stage if they want to add additional regions to their DynamoDB table.

[eric-wilson]

I also need clarification on the documentation. The docs describe a typical workflow for creating a regular table and then adding replicas (global tables). A global table is defined as one or more replicas.

AWS Docs - Creating a Global Table Turorial

However, in the CDK, a single "Global" table can exist independently (it is not a replica of anything), so we can add more replicas. This is a bit confusing.

I'm doing that now, and I didn't realize it until I found an issue with PITR not getting enabled and discovered it was creating AWS::DynamoDB::GlobalTable and not AWS::DynamoDB::Table. PITR says it's getting set on the replica (the only one table I have), but the console and cli indicate PITR is not enabled. I'm very confused at this point.