createDynamoTable

createDynamoTable is a Change Type in the Liquibase DynamoDB extension that creates a new table.

Uses

A DynamoDB table is a collection of data. It contains some number of items (rows), which may each contain any attributes (columns). For more information, see Core components of Amazon DynamoDB.

Run createDynamoTable

To run this Change Type, follow these steps:

1. Add the Change Type to your changeset, as shown in the examples on this page.
2. Specify any required attributes. Use the table on this page to see which ones your database requires.
3. Deploy your changeset by running the update command:

liquibase update

Now, Liquibase deploys your change on your DynamoDB database. By default, read operations on DynamoDB are eventually consistent. When you look at your database immediately after running liquibase update, DynamoDB may display the status of an object as CREATING, UPDATING, or DELETING. When it finishes, it displays the status as ACTIVE.

Note: If your deployment fails because the DynamoDB waiter times out or reaches a retry limit, you can modify the waiter settings using Liquibase Parameters for Amazon DynamoDB.

Available attributes

For more information, see DynamoDB API: CreateTable.

Tip: You must specify all top-level attributes marked as required. If you specify an optional attribute, you must also specify any nested attributes that it requires.

keySchema

Required.

Specifies the attributes that make up the primary key for the table. The primary key can either be a simple primary key (partition key only) or a composite primary key (partition key combined with sort key).

You must specify all attributes you use in keySchema within individual attributeDefinition objects in the attributeDefinitions array. For example, if your key schema contains the hash attribute Artist, you must also specify Artist and its data type in an attributeDefinition. However, attributeDefinitions can contain additional non-key attributes that aren't in keySchema.

keySchema has the following nested attributes:

• hashAttributeName (required): the name of the partition key. DynamoDB uses an internal hash function to evenly distribute data items across partitions, based on their partition key values.
• rangeAttributeName (required): the name of the sort key. DynamoDB stores items with the same partition key physically close together, in sorted order by the sort key value.

Note: When you specify keySchema at the top level of createDynamoTable, it applies to the primary key for the table. When you specify keySchema within localSecondaryIndex or globalSecondaryIndex, it applies to the primary key for the index.

attributeDefinitions

Required.

An array of attributeDefinition objects that describe attributes from the key schema of a table or index.

You must specify all attributes you use in keySchema within individual attributeDefinition objects in the attributeDefinitions array. For example, if your key schema contains the hash attribute Artist, you must also specify Artist and its data type in an attributeDefinition. However, attributeDefinitions can contain additional non-key attributes that aren't in keySchema.

Individual attributeDefinition objects have the following nested attributes:

• attributeName (required): the name of the attribute.
• attributeType (required): the data type of the attribute. Valid values are S (string), N (number), and B (binary).

provisionedThroughput

Sometimes required.

• If you set billingMode to PROVISIONED, or if you do not explicitly set billingMode, then provisionedThroughput is required.
• If you set billingMode to PAY_PER_REQUEST, you cannot specify provisionedThroughput.

Specifies the provisioned throughput settings for the table. You can modify these settings using the updateDynamoTable and updateTableProvisionedThroughput Change Types.

Note: If you originally set billingMode to PROVISIONED and want to change it to PAY_PER_REQUEST, you must do this with updateDynamoTable. You cannot use updateTableProvisionedThroughput because it only accepts the PROVISIONED billing mode.

provisionedThroughput has the following nested attributes:

• readCapacityUnits (required): the maximum number of reads per second before DynamoDB returns a ThrottlingException. Minimum valid value: 1.
• writeCapacityUnits (required): the maximum number of writes per second before DynamoDB returns a ThrottlingException. Minimum valid value: 1.

If you set billingMode to PAY_PER_REQUEST, Liquibase sets the values of readCapacityUnits and writeCapacityUnits to 0.

For more information, see Read/write capacity mode and Managing settings on DynamoDB provisioned capacity tables.

Note: When you specify provisionedThroughput at the top level, it applies to the table. When you specify provisionedThroughput within globalSecondaryIndex, it applies to the index.

localSecondaryIndexes

Optional.

An array of localSecondaryIndex objects to be created on the table. You can specify between 1 and 5 local secondary indexes on a particular table. Each index is scoped to a given partition key (primary key) value. There is a 10 GB size limit per partition key value, but no other size limits.

Individual localSecondaryIndex objects have the following nested attributes:

• indexName (required): the name of the local secondary index. The name must be unique among all other indexes on this table.
• keySchema (required): the key schema for the local secondary index.
  • hashAttributeName (required): the name of the partition key.
  • rangeAttributeName (required): the name of the sort key.
• projection (required): specifies attributes that are copied (projected) from the table into the index. These are in addition to the primary key attributes and index key attributes, which are automatically projected. Each attribute specification is composed of:
  • projectionType (optional): specifies which kinds of attributes are projected into the index. Valid values are KEYS_ONLY (only project the index and primary keys), INCLUDE (project the index and primary keys as well as other non-key attributes), and ALL (project all table attributes). The default value is ALL.
  • nonKeyAttributes (optional): an array of non-key attributes which will be projected into the index. You can specify between 1 and 20 non-key attributes in a single secondary index. You can specify up to 100 non-key attributes across all local and global secondary indexes on a particular table (duplicate non-key attributes are counted multiple times).
    • attributeName (optional): the name of this particular non-key attribute

globalSecondaryIndexes

Optional.

An array of individual globalSecondaryIndex objects to create on the table. You can specify between 1 and 20 global secondary indexes on a particular table.

Individual globalSecondaryIndex objects have the following nested attributes:

• indexName (required): the name of the local secondary index. The name must be unique among all other indexes on this table.
• keySchema (required): the key schema for the local secondary index.
  • hashAttributeName (required): the name of the partition key.
  • rangeAttributeName (required): the name of the sort key.
• projection (required): specifies attributes that are copied (projected) from the table into the index. These are in addition to the primary key attributes and index key attributes, which are automatically projected. Each attribute specification is composed of:
  • projectionType (optional): specifies which kinds of attributes are projected into the index. Valid values are KEYS_ONLY (only project the index and primary keys), INCLUDE (project the index and primary keys as well as other non-key attributes), and ALL (project all table attributes). The default value is ALL.
  • nonKeyAttributes (optional): an array of non-key attributes which will be projected into the index. You can specify between 1 and 20 non-key attributes in a single secondary index. You can specify up to 100 non-key attributes across all local and global secondary indexes on a particular table (duplicate non-key attributes are counted multiple times).
    • attributeName (optional): the name of this particular non-key attribute

• provisionedThroughput (optional): specifies the provisioned throughput settings for the index.
  • readCapacityUnits (required): the maximum number of reads per second before throttling.
  • writeCapacityUnits (required): the maximum number of writes per second before throttling.

tags

Optional.

An array of tag objects, which are key-value pairs you can use to label the table.

Individual tag objects have the following nested attributes:

• key (required): the case-sensitive name of the tag. Must be unique from other tag keys on the table. Cannot be null.
• value (required): the case-senstive value of the tag. Can be null.

For more information, see Tagging for DynamoDB.

streamSpecification

Optional.

The settings for DynamoDB Streams on the table.

streamSpecification has the following nested attributes:

• streamEnabled (required): indicates whether DynamoDB Streams is to be enabled (true) or disabled (false).
• streamViewType (optional): when an item in the table is modified, this specifies what to write to the table's stream about that item. Valid values are: KEYS_ONLY (only the item's key attributes), NEW_IMAGE (the entire item after it was modified), OLD_IMAGE (the entire item before it was modified), NEW_AND_OLD_IMAGES (the entire item before and after it was modified).

sseSpecification

Optional.

The settings to enable server-side encryption for the table.

sseSpecification has the following nested attributes:

• enabled (optional): if true, enables server-side encryption by the AWS Key Management Service (KMS). If false, server-side encryption uses an AWS owned key. The default value is false.
• sseType (optional): the type of server-side encryption to use. The only supported value is KMS. The key is stored in your account and is managed by AWS KMS.
• kmsMasterKeyId (optional): the AWS KMS key to use for encryption. To specify a key, use its key ID, Amazon Resource Name (ARN), alias name, or alias ARN. You should only provide this attribute if the key is different from the default DynamoDB key: alias/aws/dynamodb.

Examples

<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" kmsMasterKeyId="alias/aws/dynamodb"/>
        </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
              kmsMasterKeyId: alias/aws/dynamodb
            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": {
                "enabled": true,
                "sseType": "KMS",
                "kmsMasterKeyId": "alias/aws/dynamodb"
              },
              "streamSpecification": {
                "streamEnabled": true,
                "streamViewType": "NEW_IMAGE"
              },
              "tags": [
                {
                  "tag": {
                    "key": "tag",
                    "value": "tagValue"
                  }
                },
                {
                  "tag": {
                    "key": "tag2",
                    "value": "tagValue2"
                  }
                }
              ]
            }
          }
        ],
        "rollback": [
          {
            "deleteDynamoTable": {
              "tableName": "Music3JSON"
            }
          }
        ]
      }
    }
  ]
}

Database support

This Change Type is only supported for Amazon DynamoDB. It does not support auto rollback.