Updating global tables to Version 2019.11.21 (Current)

There are two versions of DynamoDB global tables available: Version 2019.11.21 (Current) and Version 2017.11.29 (Legacy). Customers should use version 2019.11.21 (Current) when possible, as it provides greater flexibility, higher efficiency and consumes less write capacity than 2017.11.29 (Legacy). To determine which version you are using, see Determining the global table version you are using.

This section describes how to update your global tables to Version 2019.11.21 (Current).

Before you begin

DynamoDB global tables Version 2019.11.21 (Current) introduces the following requirements:

• The global secondary indexes on the replica tables must be consistent across Regions.

• The encryption setting on the replica tables must be consistent across Regions.

• The Time to live (TTL) settings on the replica tables must be consistent across Regions. If TTL is enabled on a replica table, TTL deletes are replicated.

• DynamoDB auto scaling or on-demand capacity must be enabled for write capacity units across all replica tables.

• Global tables control plane operations (create, delete, update, and describe) APIs differ. For more information, see Global tables: Multi-Region replication with DynamoDB.

DynamoDB global tables Version 2019.11.21 (Current) introduces the following changes in behavior:

• DynamoDB Streams publishes only one record (instead of two) for each write.

• For new inserts, aws:rep:* attributes in the item record are not added.

• For updates to items that contain aws:rep:* attributes, those attributes are not updated.

• DynamoDB mapper must not require the aws:rep:* attributes for this table.

• When updating from Version 2017.11.29 (Legacy) to Version 2019.11.21 (Current), you might see an increase in the ReplicationLatency metric. This is expected because Version 2019.11.21 (Current) captures the full end-to-end measurement of replication delay between global tables Regions. For more information, see the ReplicationLatency documentation for version Version 2017.11.29 (Legacy) and Version 2019.11.21 (Current).

Required permissions

To update to Cersion 2019.11.21 (Current), you must have dynamodb:UpdateGlobalTableVersion permissions across replica Regions. These permissions are in addition to the permissions needed for accessing the DynamoDB console and viewing tables.

The following IAM policy grants permissions to update any global table to Version 2019.11.21 (Current).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "dynamodb:UpdateGlobalTableVersion",
            "Resource": "*"
        }
    ]
}

The following IAM policy grants permissions to update only the Music global table, with replicas in two Regions, to Version 2019.11.21 (Current).

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "dynamodb:UpdateGlobalTableVersion",
            "Resource": [
                "arn:aws:dynamodb::123456789012:global-table/Music",
                "arn:aws:dynamodb:ap-southeast-1:123456789012:table/Music",
                "arn:aws:dynamodb:us-east-2:123456789012:table/Music"
            ]
        }
    ]
}

Update process overview

During the update process, the state of your global table changes from ACTIVE to UPDATING.

The process takes several minutes, but it should finish in less than an hour. During the update process, your table remains available for read and write traffic. However, auto scaling does not alter the provisioned capacity on your table during the update. As such, before you begin the update, we recommend that you switch your table to on-demand capacity.

If you choose to use provisioned capacity with auto scaling during the update, you must increase the minimum read and write throughput on your policies to accommodate expected increases in traffic for the duration of the update.

When the update process is complete, your table status returns to ACTIVE. You can check the state of your table by using DescribeTable, or verify it using the Tables view on the DynamoDB console.

Important

• Updating from Version 2017.11.29 (Legacy) to Version 2019.11.21 (Current) is a one-time action and cannot be reversed. Before proceeding with the update, ensure that you have performed all necessary testing. Allow up to 60 minutes before attempting to update a newly created global table.

• In Version 2017.11.29 (Legacy) of global tables, DynamoDB performed a write operation to insert three attributes into the item record. These attributes (aws:rep:*) were used to enact replication and manage conflict resolution. In Version 2019.11.21 (Current) of global tables, replication activity is managed natively and is not exposed to users.

• Updating to Version 2019.11.21 (Current) is only available through the DynamoDB console.

Updating to Version 2019.11.21 (Current)

Follow these steps to update your version of DynamoDB global tables using the AWS Management Console.

To update global tables to Version 2019.11.21 (Current)

1. Open the DynamoDB console at https://console.aws.amazon.com/dynamodb/home.

2. In the navigation pane on the left side of the console, choose Tables, and then select the global table that you want to update to Version 2019.11.21 (Current).

3. Choose the Global Tables tab.

4. Choose Update version.

   

5. Read and agree to the new requirements, and then choose Update version.

   Important

   Updating from Version 2017.11.29 (Legacy) to Version 2019.11.21 (Current) is a one-time action and cannot be reversed. Before starting the update, ensure that you have performed all necessary testing.

6. After the update process is complete, the global tables version that appears on the console changes to 2019.11.21.