How to change the primary key or table name in DynamoDB?

AWS DynamoDB is a key-value and document database (read more about this type of database in my databases overview) managed by AWS.

One of the operations that is not so easy to do there is changing a primary key in a table or renaming the table itself. There is no straightforward way to do this because DynamoDB itself doesn’t provide such an operation directly. However, it is possible to do this using other operations that DynamoDB provides.

In this short blog post, I will show you how to perform these operations.

Rename table

The easiest way to rename a table is to Create a backup of DynamoDB table and then create a new table by restoring the backup.

The steps in the procedure are as follows:

1. Go to the table details of your existing table in DynamoDB.
2. Switch to the Backups tab.
3. Click on the Create backup button to create an on-demand backup.
4. You can change any of the backup settings if you wish, but at the time of writing the defaults are sufficient and there is no need to change them.
5. Click on the Create backup button to actually create the backup.
6. Go to the Backups section of the DynamoDB menu – note that this refers to the general DynamoDB menu, not the Backups tab of a table as in the previous step.
7. Wait for the backup to be created and visible there. This may take a while – AWS states that it can take up to 1 hour. In my case, it took about 5 minutes.
8. Select the created backup and click on the Restore button.
9. Define the new table name in the Restore settings. You can also change the encryption key or the IAM role used to perform the backup recovery process.
10. Go to the Tables section in the DynamoDB menu and find your new table there. It should be visible almost immediately and its status will initially be set to Restoring. Just wait until the table is fully restored.
11. Once the table is restored, you can replace any references to the old table with references to the new table and remove the old table.

Change primary key

Changing the primary key of a DynamoDB table can be done in several ways, but basically there are two options:

• create a new table with the new primary key and migrate the data to it,
• leave the existing table as it is and use secondary indexes – more specifically, global secondary indexes, because they can be created at any time, as opposed to local secondary indexes, which can only be created only at the same time as a table.

Which approach should be chosen? It depends on the needs and should be clear after analysing the advantages and disadvantages of both approaches.

New table

Procedure

1. Back up the existing table along with all of its data using the same approach as described above in Rename table section. It isn’t strictly needed but highly recommended to have the option to restore the table if anything goes wrong.
2. Export data from your table to S3 using the Exports to S3 option in the main DynamoDB menu. Use any format and any bucket you want for this purpose.
3. If you want to still use the same table name as currently, then the table must be deleted at this point.
4. Import the exported data from S3 using Import from S3 option in the main DynamoDB menu. During this process, you need to:
   • provide the table name – the destination name you want to use so it should be either a new name if you kept the original table or the same name as previously if you want to still use the same table name and deleted the old table in the previous step,
   • provide the new partition key which will be used by the newly created table.
5. Wait until the import procedure is completed. The table should be there with all the data and the new partition key should be set.

Advantages

• no additional costs once the table is updated,
• best possible performance when querying by the key,
• both: strong and eventual consistency is available,
• GetItem operation is available.

Disadvantages

• not useful when several primary keys are necessary, e.g. the old one (the one before migration) and the new one (the one after the migration),
• an additional risk of data corruption or loss when something goes wrong with the migration and the data is not properly backed up – it can be mitigated by restoring the backup temporarily to another table and making sure the data is properly restored there before deletion of the original table and restoring the backup to the proper table (remember to delete the redundant temporary table) but takes more time and generates additional costs,
• more effort and time are required to perform this operation compared to secondary indexes usage.

Global Secondary Index

Procedure

1. Go to the table details of your existing table in DynamoDB.
2. Switch to the Indexes tab.
3. Click on the Create index button to create a global secondary index.
4. Provide desired primary key – partition key and optionally sort key.
5. Set Index name – it will be used to query the index later so make sure to choose some meaningful name which will make the purpose of this index clear. Remember that the name must be unique globally – just like the table name must be unique – there is no possibility to create a global secondary index with the same name for another table.
6. Choose Attribute projections – if you want to have the access to all data like you have when you query the table itself, then choose the All option. But if it is enough to use the old primary key to access all data and the new primary key to access only some subset of attributes – then it’s better to choose the other options to limit the amount of data stored in the index.
7. Click on the Create index button to create the index.
8. You should be navigated back to the Indexes tab and you should be able to see your index on the Global secondary indexes list.
   Wait until the index is created – the initial status of the index should be Creating and then it should switch to Active once it’s created.

Check out the AWS documentation to see how to query the global secondary index – it’s similar to the way the table is queried.

Advantages

• the procedure takes less time than renaming the table itself,
• it is possible to define several global secondary indexes which means that it is possible to query the same table using various primary keys so if two or more different primary keys are needed – then this approach allows for it,
• no risk of data corruption – the original table and its data remains untouched.

Disadvantages

• additional costs for updated data – whenever data in the table is changed, the data in each affected global secondary index must be updated and this operation consumes write request units from the index so changing data in the table means that write request units are consumed from both: table and index (read operation isn’t affected because read from table consumes read request units only from the table and read from index consumes read request units only from the index),
• strong consistency is unavailable,
• the performance may be slower compared to querying the table directly (assuming the table has the same partition key as the index) but it can also be tweaked as the global secondary index has its own throughput settings so it is possible to set more read and/or write capacity units for index than for the table itself (when using provisioned mode),
• GetItem operation is unavailable.

Which approach is better to change the partition key?

Consider the usage of secondary indexes when you want to avoid any risk related to migration to a new table or when the existing partition key will still be useful, i.e. you want to query data by both: the existing primary key and the new one.

On the other hand, if you don’t plan to query data using the old partition key and it is enough to use a single partition key when querying the data, then the approach with additional indexes means unnecessary extra data in DynamoDB resulting in more costs and a bit lower performance.

Consider the advantages and disadvantages of every approach and choose one that suits better your needs.