Using Liquibase with Amazon DynamoDB

Amazon DynamoDB is a fully managed NoSQL database service. For an overview of the Liquibase extension for DynamoDB, see Liquibase Amazon DynamoDB Extension Overview. For more information, see the Amazon DynamoDB Documentation.

Verified versions

Cloud

Verification level

Note: A database's verification level indicates how well it works with different features in Liquibase and across different products, such as Liquibase Open Source and Liquibase Pro. For more information, see Database Verification Levels.

Foundational: Database has been tested and validated to deliver the basic functionality of change management and change tracking aligned with the database. Some additional advanced capabilities may be implemented. The Liquibase customer support team provides how-to/usage support around verified capabilities for commercial customers.

Prerequisites

Introduction to Liquibase – Dive into Liquibase concepts.
Install Liquibase – Download Liquibase on your machine.
Get Started with Liquibase – Learn how to use Liquibase with an example database.
Design Your Liquibase Project – Create a new Liquibase project folder and organize your changelogs
How to Apply Your Liquibase Pro License Key – If you use Liquibase Pro, activate your license.

Install drivers

To use Liquibase and Amazon DynamoDB, you must download the JAR file that contains the Liquibase DynamoDB extension.

To use the Liquibase CLI, place your JAR file(s) in the liquibase/lib directory.

If you use Maven, you must instead include the driver JAR as a dependency in your pom.xml file.

<dependency>
    <groupId>org.liquibase.ext</groupId>
    <artifactId>liquibase-commercial-dynamodb</artifactId>
    <version>1.0.0</version>
</dependency>

Implement Amazon DynamoDB

Configure your AWS keys as local environment variables or in your AWS configuration files. You can use these secure credentials instead of a traditional username and password. You must set the following keys:
- AWS_ACCESS_KEY_ID
- AWS_SECRET_ACCESS_KEY
- AWS_SESSION_TOKEN (optional)
Note: The Liquibase DynamoDB extension automatically detects the value of AWS_REGION from your database connection URL, so you don't have to specify it in your config file (~/.aws/config). For an example connection URL, see the Test your connection section.

In your shared credentials file (~/.aws/credentials), you can use temporary values from your AWS access portal. For example:
```
[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
aws_session_token=IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZ2luX2IQoJb3JpZVERYLONGSTRINGEXAMPLE
```
Ensure your AWS user account has Identity and Access Management (IAM) permissions to make the following API actions:

"dynamodb:CreateTable",
"dynamodb:DeleteTable",
"dynamodb:DescribeTable",
"dynamodb:ListTables",
"dynamodb:UpdateTable",
"dynamodb:BatchGetItem",
"dynamodb:BatchWriteItem",
"dynamodb:ConditionCheckItem",
"dynamodb:DeleteItem",
"dynamodb:GetItem",
"dynamodb:PutItem",
"dynamodb:UpdateItem",
"dynamodb:PartiQLDelete",
"dynamodb:PartiQLInsert",
"dynamodb:PartiQLSelect",
"dynamodb:PartiQLUpdate",
"dynamodb:Query",
"dynamodb:Scan",
"dynamodb:ListTagsOfResource",
"dynamodb:TagResource",
"dynamodb:UntagResource"

You may want to add more permissions. For a list of permission keys, see Actions, resources, and condition keys for Amazon DynamoDB.

(Optional) If you want to make operations with the sseSpecification feature, you must also have the following permissions:

"kms:DescribeKey",
"kms:CreateGrant"

(Optional) If you want to use AWS Secrets Manager, you must also have the following permissions:

"secretsmanager:DescribeSecret",
"secretsmanager:GetSecretValue",
"secretsmanager:ListSecrets",
"secretsmanager:ListSecretVersionIds"

(Optional) If you want to use changelogs from AWS S3, you must also have the following permissions:

"s3:PutObject",
"s3:GetObject",
"s3:ListBucket",
"s3:ListBucketMultipartUploads",
"s3:ListMultipartUploadParts"

(Optional) Specify custom values for Liquibase Parameters for Amazon DynamoDB. This is only necessary if you do not want to use the default Liquibase values. You can set these in your command line (CLI), in your liquibase.properties file, or as environment varibles. There are two groups of parameters:
1. Those that specify the initial billing modes and read/write capacity for Liquibase tracking tables: DATABASECHANGELOG and DATABASECHANGELOGLOCK.
2. Those that specify the number of polling attempts, time between attempts, total timeouts, and timeout behavior for the DynamoDB waiter to use when running create, update, and delete operations through Liquibase.

Test your connection

Ensure your Amazon DynamoDB database is configured. For more information, see Amazon: Setting Up DynamoDB.
Specify the database URL in the liquibase.properties file (defaults file), along with other properties you want to set a default value for. Liquibase does not parse the URL. You can either specify the full database connection string or specify the URL using your database's standard connection format:
- Cloud: url: https://dynamodb.<region>.amazonaws.com
- Local: url: dynamodb://localhost:8000

Note: For a list of AWS regions and other parameters that you can use in your URL, see AWS service endpoints. For example, url: https://dynamodb.us-west-2.amazonaws.com.

Tip: To apply a Liquibase Pro key to your project, add the following property to the Liquibase properties file: licenseKey: <paste code here>

Create a text file called changelog (.xml, .yaml, or .json) in your project directory and add a changeset.

<databaseChangeLog
    xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:dynamodb="http://www.liquibase.org/xml/ns/pro-dynamodb"
    xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog  http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-latest.xsd
    http://www.liquibase.org/xml/ns/pro-dynamodb http://www.liquibase.org/xml/ns/pro-dynamodb/liquibase-pro-dynamodb-latest.xsd">

    <changeSet id="1" author="your.name">
        <dynamodb:createDynamoTable tableName="Music3XML" billingMode="PROVISIONED" tableClass="STANDARD" deletionProtectionEnabled="false">
            <dynamodb:keySchema hashAttributeName="Artist" rangeAttributeName="SongTitle"/>
            <dynamodb:attributeDefinitions>
                <dynamodb:attributeDefinition attributeName="Artist" attributeType="S"/>
                <dynamodb:attributeDefinition attributeName="SongTitle" attributeType="S"/>
                <dynamodb:attributeDefinition attributeName="Album" attributeType="N"/>
            </dynamodb:attributeDefinitions>
            <dynamodb:provisionedThroughput readCapacityUnits="5" writeCapacityUnits="5"/>
            <dynamodb:localSecondaryIndexes>
                <dynamodb:localSecondaryIndex indexName="localSecondaryIndex">
                    <dynamodb:keySchema hashAttributeName="Artist" rangeAttributeName="Album"/>
                    <dynamodb:projection projectionType="INCLUDE">
                        <dynamodb:nonKeyAttributes attributeName="SongTitle"/>
                    </dynamodb:projection>
                </dynamodb:localSecondaryIndex>
            </dynamodb:localSecondaryIndexes>
            <dynamodb:globalSecondaryIndexes>
                <dynamodb:globalSecondaryIndex indexName="SongTitleGlobalIndex">
                    <dynamodb:keySchema hashAttributeName="Artist" rangeAttributeName="SongTitle"/>
                    <dynamodb:projection projectionType="INCLUDE">
                        <dynamodb:nonKeyAttributes attributeName="Album"/>
                    </dynamodb:projection>
                    <dynamodb:provisionedThroughput readCapacityUnits="5" writeCapacityUnits="5"/>
                </dynamodb:globalSecondaryIndex>
            </dynamodb:globalSecondaryIndexes>
            <dynamodb:tags>
                <dynamodb:tag key="tag" value="tagValue"/>
                <dynamodb:tag key="tag2" value="tagValue2"/>
            </dynamodb:tags>
            <dynamodb:streamSpecification streamEnabled="true" streamViewType="NEW_IMAGE"/>
            <dynamodb:sseSpecification enabled="true" sseType="KMS"/>
        </dynamodb:createDynamoTable>

        <rollback>
            <dynamodb:deleteDynamoTable tableName="Music3XML"/>
        </rollback>
    </changeSet>

</databaseChangeLog>

databaseChangeLog:
  - changeSet:
      id: 1
      author: your.name
      changes:
        - createDynamoTable:
            tableName: Music3YAML
            billingMode: PROVISIONED
            tableClass: STANDARD
            deletionProtectionEnabled: false
            keySchema:
              hashAttributeName: Artist
              rangeAttributeName: SongTitle
            attributeDefinitions:
              - attributeDefinition:
                  attributeName: Artist
                  attributeType: S
              - attributeDefinition:
                  attributeName: SongTitle
                  attributeType: S
              - attributeDefinition:
                  attributeName: Album
                  attributeType: N
            provisionedThroughput:
                readCapacityUnits: 5
                writeCapacityUnits: 5
            localSecondaryIndexes:
                - localSecondaryIndex:
                    indexName: localSecondaryIndex
                    keySchema:
                      hashAttributeName: Artist
                      rangeAttributeName: Album
                    projection:
                        projectionType: INCLUDE
                        nonKeyAttributes:
                          - attributeName: SongTitle
            globalSecondaryIndexes:
                - globalSecondaryIndex:
                    indexName: SongTitleGlobalIndex
                    keySchema:
                      hashAttributeName: Artist
                      rangeAttributeName: SongTitle
                    projection:
                        projectionType: INCLUDE
                        nonKeyAttributes:
                          - attributeName: Album
                    provisionedThroughput:
                        readCapacityUnits: 5
                        writeCapacityUnits: 5
            streamSpecification:
              streamEnabled: true
              streamViewType: NEW_IMAGE
            sseSpecification:
              enabled: true
              sseType: KMS
            tags:
              - key: tag
                value: tagValue
              - key: tag2
                value: tagValue2
      rollback:
        deleteDynamoTable:
          tableName: Music3YAML

{
  "databaseChangeLog": [
    {
      "changeSet": {
        "id": "1",
        "author": "your.name",
        "changes": [
          {
            "createDynamoTable": {
              "tableName": "Music3JSON",
              "billingMode": "PROVISIONED",
              "tableClass": "STANDARD",
              "deletionProtectionEnabled": false,
              "keySchema": {
                "hashAttributeName": "Artist",
                "rangeAttributeName": "SongTitle"
              },
              "attributeDefinitions": [
                {
                  "attributeDefinition": {
                    "attributeName": "Artist",
                    "attributeType": "S"
                  }
                },
                {
                  "attributeDefinition": {
                    "attributeName": "SongTitle",
                    "attributeType": "S"
                  }
                },
                {
                  "attributeDefinition": {
                    "attributeName": "Album",
                    "attributeType": "N"
                  }
                }
              ],
              "provisionedThroughput": {
                "readCapacityUnits": 5,
                "writeCapacityUnits": 5
              },
              "localSecondaryIndexes": [
                {
                  "localSecondaryIndex": {
                    "indexName": "localSecondaryIndex",
                    "keySchema": {
                      "hashAttributeName": "Artist",
                      "rangeAttributeName": "Album"
                    },
                    "projection": {
                      "projectionType": "INCLUDE",
                      "nonKeyAttributes": [
                        {
                          "attributeName": "SongTitle"
                        }
                      ]
                    }
                  }
                }
              ],
              "globalSecondaryIndexes": [
                {
                  "globalSecondaryIndex": {
                    "indexName": "SongTitleGlobalIndex",
                    "keySchema": {
                      "hashAttributeName": "Artist",
                      "rangeAttributeName": "SongTitle"
                    },
                    "projection": {
                      "projectionType": "INCLUDE",
                      "nonKeyAttributes": [
                        {
                          "attributeName": "Album"
                        }
                      ]
                    },
                    "provisionedThroughput": {
                      "readCapacityUnits": 5,
                      "writeCapacityUnits": 5
                    }
                  }
                }
              ],
              "sseSpecification": {
                "enable": true,
                "sseType": "KMS"
              },
              "streamSpecification": {
                "streamEnabled": true,
                "streamViewType": "NEW_IMAGE"
              },
              "tags": [
                {
                  "tag": {
                    "key": "tag",
                    "value": "tagValue"
                  }
                },
                {
                  "tag": {
                    "key": "tag2",
                    "value": "tagValue2"
                  }
                }
              ]
            }
          }
        ],
        "rollback": [
          {
            "deleteDynamoTable": {
              "tableName": "Music3JSON"
            }
          }
        ]
      }
    }
  ]
}

Navigate to your project folder in the CLI and run the Liquibase status command to see whether the connection is successful:

liquibase status --changelog-file=<changelog.xml>

Note: You can specify arguments in the CLI or keep them in the Liquibase properties file.

If your connection is successful, you'll see a message like this:

4 changesets have not been applied to <your_connection_url>
Liquibase command 'status' was executed successfully.

Then make changes to your database with the update command:

liquibase update --changelog-file=<changelog.xml>

If your update is successful, Liquibase runs each changeset and displays a summary message ending with:

Liquibase: Update has been successful.
Liquibase command 'update' was executed successfully.

From a database UI tool, ensure that your database contains the Music3<format> object you added along with the DATABASECHANGELOG table and DATABASECHANGELOGLOCK table.

Now you're ready to start making deployments with Liquibase!

Supported features

To see a list of supported Liquibase features in Amazon DynamoDB, see the Liquibase Amazon DynamoDB Extension Overview.

You can use most Liquibase commands in Amazon DynamoDB except database inspection commands and commands that generate SQL.

For examples of Change Types and parameters for Amazon DynamoDB, see the following pages:

Using Liquibase with Amazon DynamoDB

Verified versions

Verification level

Prerequisites

Install drivers

Implement Amazon DynamoDB

Test your connection

Supported features

Related links