Legacy and Current version behavior differences Upgrade prerequisites Required permissions What to expect during the upgrade DynamoDB Streams behavior Upgrading to version 2019.11.21 (Current)

Upgrading your DynamoDB global tables from version 2017.11.29 (Legacy) to version 2019.11.21 (Current)

Note

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

This section describes how to upgrade your global tables to version 2019.11.21 (Current) using the DynamoDB console. Upgrading from version 2017.11.29 (Legacy) to version 2019.11.21 (Current) is a one-time action and you cannot reverse it. Currently, you can upgrade global tables using the console only.

Topics

Legacy and Current version behavior differences
Upgrade prerequisites
Required permissions
What to expect during the upgrade
DynamoDB Streams behavior
Upgrading to version 2019.11.21 (Current)

Differences in behavior between Legacy and Current versions

The following list describes the differences in behavior between the Legacy and Current versions of global tables.

version 2019.11.21 (Current) consumes less write capacity for several DynamoDB operations compared to version 2017.11.29 (Legacy), and therefore, is more cost-effective for most customers. The differences for these DynamoDB operations are as follows:

Invoking PutItem for a 1KB item in a Region and replicating to other Regions requires 2 rWRUs per region for 2017.11.29 (Legacy), but only 1 rWRU for 2019.11.21 (Current).
Invoking UpdateItem for a 1KB item requires 2 rWRUs in the source Region and 1 rWRU per destination Region for 2017.11.29 (Legacy), but only 1 rWRU for both source and destination Regions for 2019.11.21 (Current).
Invoking DeleteItem for a 1KB item requires 1 rWRU in the source Region and 2 rWRUs per destination Region for 2017.11.29 (Legacy), but only 1 rWRU for both source or destination Region for 2019.11.21 (Current).

The following table shows the rWRU consumption of 2017.11.29 (Legacy) and 2019.11.21 (Current) tables for a 1KB item in two Regions.

Operation	2017.11.29 (Legacy)	2019.11.21 (Current)	Savings
PutItem	4 rWRUs	2 rWRUs	50%
UpdateItem	3 rWRUs	2 rWRUs	33%
DeleteItem	3 rWRUs	2 rWRUs	33%

version 2017.11.29 (Legacy) is available in only 11 AWS Regions. However, version 2019.11.21 (Current) is available in all the AWS Regions.
You create version 2017.11.29 (Legacy) global tables by first creating a set of empty Regional tables, then invoking the CreateGlobalTable API to form the global table. You create version 2019.11.21 (Current) global tables by invoking the UpdateTable API to add a replica to an existing Regional table.
version 2017.11.29 (Legacy) requires you to empty all replicas in the table before adding a replica in a new Region (including during creation). version 2019.11.21 (Current) supports you to add and remove replicas to Regions on a table that already contains data.
version 2017.11.29 (Legacy) uses the following dedicated set of control plane APIs for managing replicas:
version 2019.11.21 (Current) uses the DescribeTable and UpdateTable APIs to manage replicas.
version 2017.11.29 (Legacy) publishes two DynamoDB Streams records for each write. version 2019.11.21 (Current) only publishes one DynamoDB Streams record for each write.
version 2017.11.29 (Legacy) populates and updates the aws:rep:deleting, aws:rep:updateregion, and aws:rep:updatetime attributes. version 2019.11.21 (Current) does not populate or update these attributes.
version 2017.11.29 (Legacy) does not synchronize Using time to live (TTL) in DynamoDB settings across replicas. version 2019.11.21 (Current) synchronizes TTL settings across replicas.
version 2017.11.29 (Legacy) does not replicate TTL deletes to other replicas. version 2019.11.21 (Current) replicates TTL deletes to all replicas.
version 2017.11.29 (Legacy) does not synchronize auto scaling settings across replicas. version 2019.11.21 (Current) synchronizes auto scaling settings across replicas.
version 2017.11.29 (Legacy) does not synchronize global secondary index (GSI) settings across replicas. version 2019.11.21 (Current) synchronizes GSI settings across replicas.
version 2017.11.29 (Legacy) does not synchronize encryption at rest settings across replicas. version 2019.11.21 (Current) synchronizes encryption at rest settings across replicas.
version 2017.11.29 (Legacy) publishes the PendingReplicationCount metric. version 2019.11.21 (Current) does not publish this metric.

Upgrade prerequisites

Before you start upgrading to version 2019.11.21 (Current) global tables, you must fulfill the following prerequisites:

Using time to live (TTL) in DynamoDB settings on replicas are consistent across Regions.
Global secondary index (GSI) definitions on replicas are consistent across Regions.
Encryption at rest settings on replicas are consistent across Regions.
DynamoDB auto scaling is enabled for WCUs for all replicas, or on-demand capacity mode is enabled for all replicas.
Applications don't require the presence of the of aws:rep:deleting, aws:rep:updateregion, and aws:rep:updatetime attributes in table items.

Required permissions for global tables upgrade

To upgrade to version 2019.11.21 (Current), you must have dynamodb:UpdateGlobalTableversion permissions in all Regions with replicas. These permissions are required in addition to the permissions needed for accessing the DynamoDB console and viewing tables.

The following IAM policy grants permissions to upgrade 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 upgrade 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"
            ]
        }
    ]
}

What to expect during the upgrade

All global table replicas will continue to process read and write traffic while upgrading.
The upgrade process requires between a few minutes to several hours depending on the table size and number of replicas.
During the upgrade process, the value of TableStatus will change from ACTIVE to UPDATING. You can view the status of the table by invoking the DescribeTable API, or with the Tables view in the DynamoDB console.
Auto scaling will not adjust the provisioned capacity settings for a global table while the table is being upgraded. We strongly recommend that you set the table to on-demand capacity mode during the upgrade.
If you choose to use provisioned capacity mode with auto scaling during the upgrade, you must increase the minimum read and write throughput on your policies to accommodate any expected increases in traffic to avoid throttling during the upgrade.
When the upgrade process is complete, your table status will change to ACTIVE.

DynamoDB Streams behavior before, during, and after upgrade

Upgrading to version 2019.11.21 (Current)

Perform the following steps to upgrade your version of DynamoDB global tables using the AWS Management Console.

To upgrade global tables to version 2019.11.21 (Current)

Open the DynamoDB console at https://console.aws.amazon.com/dynamodb/home.
In the navigation pane on the left side of the console, choose Tables, and then select the global table that you want to upgrade to version 2019.11.21 (Current).
Choose the Global Tables tab.
Choose Update version.
Read and agree to the new requirements, and then choose Update version.
After the upgrade process is complete, the global tables version that appears on the console changes to 2019.11.21.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Determining the version

Global tables billing

Operation	Replica Region	Behavior before upgrade	Behavior during upgrade	Behavior after upgrade
Put or Update	Source	Timestamp population happens using UpdateItem.	Timestamp population happens using PutItem.	No customer visible timestamp is generated.
		Two Streams records are generated. The first record contains the customer written attributes. The second record contains the `aws:rep:*` attributes.	Two Streams records are generated. The first record contains the customer written attributes. The second record contains the `aws:rep:*` attributes.	A single Streams record is generated containing the customer-writen attributes.
		Two rWCUs are consumed for each customer write.	Two rWCUs are consumed for each customer write.	One rWCU is consumed for each customer write.
		`ReplicationLatency` and `PendingReplicationCount` metrics are published in CloudWatch.	`ReplicationLatency` and `PendingReplicationCount` metrics are published in CloudWatch.	`ReplicationLatency` metric is published in CloudWatch.
	Destination	Replication happens using PutItem.	Replication happens using PutItem.	Replication happens using PutItem.
		A single Streams record is generated, which contains both the customer-written attributes and the `aws:rep:*` attributes.	A single Streams record is generated, which contains both the customer-written attributes and the `aws:rep:*` attributes.	A single Streams record is generated, which contains the customer-written attributes only and no replication attributes.
		One rWCU is consumed if the item exists in the destination Region. Two rWCUs are consumed if the item doesn't exist in the destination Region.	One rWCU is consumed if the item exists in the destination Region. Two rWCUs are consumed if the item doesn't exist in the destination Region.	One rWCU is consumed for each customer write.
		`ReplicationLatency` and `PendingReplicationCount` metrics are published in CloudWatch.	`ReplicationLatency` and `PendingReplicationCount` metrics are published in CloudWatch.	`ReplicationLatency` metric is published in CloudWatch.
Delete	Source	Delete any item with smaller timestamp using DeleteItem.	Delete any item with smaller timestamp using DeleteItem.	Delete any item with smaller timestamp using DeleteItem.
		A single Streams record is generated, which contains both the customer-written attributes and the `aws:rep:*` attributes.	A single Streams record is generated, which contains both the customer-written attributes and the `aws:rep:*` attributes.	A single Streams record is generated, which contains the customer-written attributes.
		One rWCU is consumed for each customer delete.	One rWCU is consumed for each customer delete.	One rWCU is consumed for each customer delete.
		`ReplicationLatency` and `PendingReplicationCount` metrics are published in CloudWatch.	`ReplicationLatency` and `PendingReplicationCount` metrics are published in CloudWatch.	`ReplicationLatency` metric is published in CloudWatch.
	Destination	Two-phase deletes take place: In Phase 1, UpdateItem sets the deleting flag. In Phase 2, DeleteItem deletes the item.	Deletes the item using DeleteItem.	Deletes the item using DeleteItem.
		Two Streams records are generated. The first record contains the change to the `aws:rep:deleting` field. The second record contains the customer-written attributes and the `aws:rep:*` attributes.	A single Stream record is generated, which contains the customer-written attributes.	A single Stream record is generated, which contains the customer-written attributes.
		Two rWCUs are consumed for each customer delete.	One rWCU is consumed for each customer delete.	One rWCU is consumed for each customer delete.
		`ReplicationLatency` and `PendingReplicationCount` metrics are published in CloudWatch.	`ReplicationLatency` metric is published in CloudWatch.	`ReplicationLatency` metric is published in CloudWatch.