dynamodb-waiters-enabled

--dynamodb-waiters-enabled is a global Boolean parameter for the Liquibase DynamoDB Pro extension. It specifies whether to enable or disable the DynamoDbWaiter for all Liquibase DynamoDB operations. The default value is true.

When true, Liquibase waits for DynamoDB operations in a changeset to be fully complete before moving onto the next changeset. When false, Liquibase moves onto the next changeset while the first one may still be in a pending state, potentially saving time. When false, Liquibase also suppresses all other --dynamodb-waiter-* parameters.

Warning: If you set this parameter to false, you risk unexpected behavior. You must ensure that any changesets you deploy do not try to access objects that are in a pending state.

Note: The Liquibase Tracking Tables (DATABASECHANGELOG and DATABASECHANGELOGLOCK) always use waiters, regardless of the value you specify for --dynamodb-waiters-enabled.

Uses

When you ask Amazon DynamoDB to run an operation on a resource in your database, such as creating, updating, or deleting a table, DynamoDB calls a waiter class first. Waiters are AWS SDK objects that ensure consistency in distributed systems when DynamoDB doesn't perform operations instantly, but some code needs to wait until those operations are fully completed.

The waiter repeatedly checks whether the table is in the correct state (it "polls" the table). If the table is in the correct state (ACTIVE or non-existent), the waiter approves the operation. Otherwise, if the table status is CREATING, UPDATING, or DELETING, it tries polling again. The waiter repeats this indefinitely or until it times out. For more information, see Poll for resource states in the AWS SDK for Java 2.x: Waiters.

Note: Liquibase does not use Amazon DynamoDB waiters when you create, update, or delete indexes.

When you run Liquibase commands like update and rollback, Liquibase runs your changesets sequentially. For every change, it waits a default amount of time for DynamoDB to respond before moving onto the next changeset. The default waiter settings are appropriate for most situations. However, some operations may require custom waiter values to avoid errors or keep your CI/CD pipeline efficient.

You can customize the following behavior with Liquibase waiter parameters:

• Enabled: whether the waiter makes any polling attempts
• Interval: how long to wait between polling attempts
• Attempts: how many times to attempt to poll the resource
• Timeout: the total amount of time to spend polling
• Exit code: whether Liquibase fails after a waiter timeout
• Logs: whether Liquibase tells you about the status of the waiter, and how often to do so

The --dynamodb-waiters-enabled parameter controls whether the DynamoDB waiter is enabled for Liquibase operations:

• If you want Liquibase to wait for each changeset to finish deploying in DynamoDB before running the next changeset, no matter how long the DynamoDB operations take, leave the parameter at its default value of true. This ensures that your changesets cannot unintentionally access objects in a pending state, but may take longer.
• If you want Liquibase to not wait for each changeset to finish deploying in DynamoDB before running the next changeset, set the parameter to false. This ensures that your CI/CD workflow moves forward rapidly, but may result in unexpected behavior.

Tip: If you set this parameter to false, you must be certain that the later changes in your changelog will not try to access objects modified earlier in your changelog (which may still be running and may be in a pending state).

Syntax

You can set this parameter in the following ways:

liquibase.dynamodb.waiters.enabled: <true|false>

stages:
  Default:
    actions:
      - type: liquibase
        command: update
        globalArgs: { dynamodb-waiters-enabled: "<true|false>" }

liquibase
 --dynamodb-waiters-enabled=<true|false> update
 --changelog-file=example-changelog.xml

JAVA_OPTS=-Dliquibase.dynamodb.waiters.enabled=<true|false>

LIQUIBASE_DYNAMODB_WAITERS_ENABLED=<true|false>

For more information, see Working with Command Parameters.

Troubleshooting

If you disable waiters, Liquibase may sometimes attempt to modify a pending resource:

Unexpected error running Liquibase: Migration failed for changeset changelogs/example-changelog.xml::2::your.name:
     Reason: liquibase.exception.DatabaseException: Could not execute
  - Caused by: Attempt to change a resource which is still in use: Table is being created: Music (Service: DynamoDb, Status Code: 400, Request ID: 61FCQO19S8P91M5TD8RCTAU60NVV4KQNSO5AEMVJF66Q9ASUAAJG)

If you experience this issue, you should re-run your failed change after waiting enough time for the resource to be in an ACTIVE state. Alternatively, you can re-enable waiters and set higher wait times if necessary.

Related links

• Poll for resource states in the AWS SDK for Java 2.x: Waiters