Upgrade your Amazon DynamoDB global tables to the current version

Amazon DynamoDB is a fully managed, serverless NoSQL database that delivers single-digit millisecond performance for applications at any scale. DynamoDB global tables is a multi-active database feature that replicates data across AWS Regions, enabling local reads and writes.

The first version of DynamoDB global tables launched in 2017. Incorporating two years of customer feedback, in 2019 a new version of global tables was released, significantly improving replication efficiency and ease of use. While DynamoDB does not have software versions, these changes for global tables were so significant that version names were assigned to make it easier to distinguish which version of global tables was in use. The original version of global tables is version 2017.11.29 (Legacy), and the current version of global tables is version 2019.11.21 (Current). For simplicity, we refer to version 2017.11.29 as the Legacy version, and to version 2019.11.21 as the Current version. In this post, we explain why we strongly recommend all customers use the Current version for all global tables.

Global tables versions

The Legacy version of global tables uses a dedicated set of global tables APIs. Legacy global tables are created by first creating an empty DynamoDB table in each Region where a global table replica should be created, then invoking the CreateGlobalTable API to join these empty tables into a global table. New replicas are added to a Legacy global table by creating an empty table in the new Region, then calling UpdateGlobalTable to add the empty table as a replica. These empty tables must be defined with identical names, primary keys, and global secondary index settings for global table creation to succeed. Additionally, you must use the same provisioned throughput settings for all replicas when you create your Legacy version global table, and keep them identical for as long as the table exists. The Legacy version of global tables does not automatically synchronize any settings across replica tables, meaning you must manually ensure settings like time-to-live (TTL) and write capacity are the same across replicas, or risk encountering unexpected behavior.

The Current version of global tables uses the same DynamoDB APIs that are used for other table management actions. A global table is created or extended by calling the UpdateTable API on an existing single-Region table or global table and specifying a Region in which to create a new replica. The Current version of global tables automatically creates and populates new replicas without requiring you to first create empty tables in the new Region and manually ensure those replicas have the same settings as the rest of the global table. The Current version supports creating global tables replicas from tables that already contain data, and automatically synchronizes settings like TTL and write capacity across replicas when modified, simplifying the user experience.

Current version advantages

Operational benefits of the Current version

While upgrading to DynamoDB global tables’ Current version requires meticulous planning to meet prerequisites, accommodate application changes, and understand potential pitfalls, the actual upgrade process is straightforward. You can initiate the upgrade with a single button click in the DynamoDB section of the AWS management console, with changes applied instantaneously to all replica tables and their matching global secondary indexes. This seamless upgrade process is just the beginning of the advantages offered by the Current version, which brings significant improvements in availability, operational efficiency, and cost:

• The Current version of global tables are available in all AWS Regions where DynamoDB is supported, allowing you to deploy applications that serve users globally while maintaining high availability and reliability.
• It streamlines global application deployment by allowing you to add replicas to tables that may already contain data, enabling seamless expansion into new Regions without downtime.
• It automatically synchronizes key table settings-such as on-demand or provisioned write capacity mode, auto scaling configurations for write capacity, and TTL settings-across all replicas, reducing manual configuration and ensuring consistency.
• It automates replication of data across Regions, hiding all the complexity associated with data replication and conflict resolution while monitoring capabilities are improved through enhanced metrics tracking and dimension granularity. Due to simplified cross Region data replication, the Current version costs are lower for most workloads.

The Current version offers lower costs for most workloads

DynamoDB charges for global tables based on the resources consumed by each replica table. Write requests are billed using replicated write capacity units (rWCUs) instead of standard WCUs, and the number of rWCUs required for replication depends on the global tables version you use, while the cost per rWCU depends on your global table’s regions. The Current version of global tables is significantly more efficient than the Legacy version, consuming up to 50% less write capacity for common operations. Table 1 shows a write capacity consumption comparison between versions for a two Region global table with 1KB items:

Table 1 – Reduction in rWCU consumption for Current version

Table 2 shows the cost differences between the two-Region Legacy version global table and the Current version global table. In our example, each item in the Legacy table is 1 KB. Each day, we insert 100,000 items, update 10,000 items, and delete 10,000 items. We then compare these results with those from the Current version global table.

Table 2 – Example rWCU comparison Legacy and Current version

In this scenario, upgrading to the current version will reduce write consumption and, as a result, lower write costs by about 47 percent.

Upgrading to the Current version

Prerequisites

Before upgrading a global table to its Current version, you must ensure that the Legacy version fulfills the following prerequisites:

• TTL settings must be consistent across all Current version replicas. To verify TTL settings on AWS management console, navigate to the Time to Live section for each replica and confirm the TTL attribute name and status match. Another option for you is to use the DescribeTimeToLive API.
• Legacy global tables allow divergent GSI configurations between replicas. Prior to starting the upgrade process, you must make sure that global secondary index definitions are consistent across all replicas. To verify Legacy global table GSIs, check the Indexes tab in AWS management console for each replica. GSI names, key schemas, and projection types must be consistent across all the replicas. Alternatively you can use the DescribeTable API, and verify consistent global table indexes in the response.
• Legacy global tables can have different encryption settings across replicas, which may create security risks and compliance gaps. Before upgrading to the Current version, ensure all replicas have identical encryption settings. You can confirm consistent encryption status across all Legacy global table replicas in the AWS Management Console or by using the DescribeTable API. The Current version global tables support different AWS KMS keys per Region, providing enhanced flexibility and aligning with common deployment patterns. This feature allows organizations to meet region-specific compliance requirements while maintaining a global table structure. When using the Current version, you can configure and manage distinct encryption keys for each region as needed.
• DynamoDB autoscaling must be enabled if using provisioned capacity mode, or on-demand capacity mode must be enabled. Verify both these settings in AWS management console.
• To upgrade to the Current version of global tables, you need the dynamodb:UpdateGlobalTableversion permission in every Region where your table has replicas. This permission is required in addition to those needed for accessing the DynamoDB console and viewing tables. The example policy below grants permissions on a Legacy version global table with one replica.

Figure 1 – Permissions required for upgrade

• The upgrade process from the Legacy version to the Current version of DynamoDB global tables is designed to be safe and does not modify your data. However, it is always a best practice to create a backup of your Legacy version tables before starting the upgrade.

Behavior differences between versions

Before upgrading a global table, you should understand the behavior differences between the Legacy and Current versions. Depending on your application’s use of Legacy version global table specific attributes, you may need to take steps to mitigate impact.

• In the Legacy version of DynamoDB global tables, you rely on system attributes like aws:rep:updateregion, aws:rep:updatetime, and aws:rep:deleting for conflict resolution, but in the Current version, DynamoDB replaces attribute based conflict resolution with internal vector clocks and timestamp-based resolution. If your application references these system attributes, it may break after the upgrade. To prevent this, review your application code for any direct references to aws:rep:* attributes-don’t rely on Scan or Query operations alone, as they won’t reveal code dependencies. Instead, actively audit and update any logic in your code that depends on these attributes before you migrate to the current version.
• In the Legacy version of DynamoDB global tables, replication writes that populated the aws:rep:* attributes were included in DynamoDB Streams, as a result, stream records captured both customer-initiated changes and replication events. In the Current version, these replication writes and their associated aws:rep:* attributes are no longer performed or emitted to streams. As a result, only customer-initiated changes appear in stream records after upgrading.
• As described in Table 1, the Current version of global tables reduces the write capacity units (WCU) consumption for most workloads. This reduction, combined with support for both provisioned and on-demand capacity modes, makes it easier to predict and optimize your global tables costs.
• Legacy version of global tables publishes the metric PendingReplicationCount, which the Current version global tables do not expose. Instead, you should use the ReplicationLatency metric for monitoring the health of Current version global tables. Please refer to the complete list of DynamoDB global tables metrics and dimensions for more information.
• You can find additional information about upgrading to the Current version of DynamoDB global tables in upgrade documentation.

Upgrading a global table

Upgrading to the Current version of global tables can be accomplished with a single click in the DynamoDB section of AWS management console.

Figure 2 – Amazon DynamoDB Console screenshot highlighting the (selected) Global tables tab and the Update version button.

There is no interruption in availability during the upgrade, and you can continue to read and write to your global table replicas while the upgrade is in progress. Global tables that have been upgraded to the Current version cannot later be downgraded to the Legacy version. Instructions for upgrading a global table can be found in the upgrade documentation.

Post-Upgrade Validation

You will be ready to validate upgrade success, once table status shows as ACTIVE (not UPDATING) in the DynamoDB console or via the DescribeTable API. You will also see that the global table version is listed as 2019.11.21 (Current) instead of the legacy version. We list additional validations that you can perform to confirm that upgrade is complete with data accessibility in all the replica regions:

• Ensure that you can access all the replicas by performing read and write operations in each region. To do this, insert a test item in one region and verify that it appears in all other regions. Similarly, update or delete the test item in another region and confirm that the changes are reflected across every replica. For example, insert an item in us-east-1 Region with PutItem. Perform a GetItem for the same item in the replica region, say us-west-1. Make sure that the items are identical.
• Verify conflict resolution by performing concurrent writes across multiple regions, then verify the accuracy of replication by confirming that all items are identical when read from each region.
• Perform benchmarking for write latency using SuccessfulRequestLatency CloudWatch metric.
• Confirm reduced WCU consumption for PutItem, UpdateItem, and DeleteItem operations.
• You can optionally perform a disaster recovery testing. With AWS Fault Injection Simulator – FIS, you can pause replication to a specific region and observe how your application responds, including verifying that read and write operations are redirected to other available regions as expected. With this approach you can emulate controlled, real-world failover testing and validate your application’s resilience and recovery processes after the upgrade

Common challenges during the upgrade process

Upgrading to the Current version of global tables eliminates legacy limitations but requires meticulous planning to avoid configuration mismatches, tooling incompatibilities, and data inconsistencies. By auditing settings, updating tooling, and validating after migration is of paramount importance. Following is the list of the most common failure scenarios and mitigations:

• If you have inconsistencies with TTL settings or GSI configurations across replicas in the Legacy version, the upgrade may be rejected. For example, if your auto scaling settings for write capacity units are not uniform-such as setting a minimum of 10 and maximum of 1,000 in one region, but different min/max values in another-you violate the current version’s requirement for consistent auto scaling configurations across all replicas. Use DescribeGlobalTableSettings for each regional replica to check for configuration drifts, and correct any differences with the UpdateGlobalTableSettings API.
• The dynamodb:UpdateGlobalTableVersion permission is mandatory in all regions that has replicas during the upgrade. Missing permissions in even one region will block the process with AccessDeniedException. If you encounter this error, first identify and correct any IAM policies that are explicitly denying this permission to the principal initiating the upgrade process. Ensure the appropriate IAM policy granting dynamodb:UpdateGlobalTableVersion is attached to all relevant regions. To prevent issues before they occur and to verify your changes after troubleshooting, it’s recommended that you validate permissions using the AWS Policy Simulator before starting or retrying the upgrade process.
• Outdated AWS SDKs or CLI versions may lack support for the 2019.11.21 API model. Upgrade CLI/SDKs to versions supporting 2019.11.21 such as AWS CLI v2+.
• Regional autoscaling policies or mixed billing modes, where some replicas use provisioned capacity and others use on-demand capacity, in Legacy version global tables conflict with the Current version’s requirement for globally synchronized settings. If you attempt to upgrade a table with these configurations, ValidationException error occurs. To resolve this, make sure all replicas use the same billing mode by setting every replica to either provisioned capacity or on-demand capacity. Additionally, apply consistent auto scaling settings across all replicas using Application Auto Scaling using UpdateGlobalTableSettings API before you start the upgrade process.

Conclusion

AWS recommends all customers use the Current version of global tables, as it delivers enhanced cost efficiency, automated management, and robust multi-region resilience. To ensure a successful upgrade, it’s important to review your Legacy version global table configurations, update your tooling, and modify your applications if needed. Upgrading to the Current version of DynamoDB global tables is easy, and can be accomplished with just a few clicks in the DynamoDB console. Post-migration, validate performance, and continue to monitor global table performance. For more complex environments, AWS Support and the DynamoDB Well-Architected Lens provide helpful resources and best practices to guide your transition.

For more detailed information, see the Upgrading your DynamoDB global tables documentation.

About the authors

Shilpa Bondale is a Solutions Architect at AWS, specializing in helping North American software and internet clients deploy mission-critical workloads and generative AI systems on AWS infrastructure. A seasoned database and machine learning developer and architect, she advocates for women in technology and advises Women Who Code, reflecting AWS’s commitment to inclusive engineering practices.

Tyler Replogle is a principal solutions architect and technical databases leader at AWS for Worldwide Public Sector. He enables AWS Partners and customers to run their end-mission solutions on AWS. He enjoys building and has found ways to connect with his three daughters through building with Lego, Minecraft, and coding.

Diana Conner is a Senior Sales Specialist at Amazon Web Services, empowering innovative organizations to modernize their digital transformation to drive innovation and growth through cloud solutions. She specializes in modern data foundations, analytics, AI and GenAI.