dynamodb-waiter-update-total-timeout

--dynamodb-waiter-update-total-timeout is a global parameter for the Liquibase DynamoDB extension. It specifies the total number of seconds for the DynamoDbWaiter to wait for the table to be updated and operable. If the waiter sees that the table is in the correct state, the operation finishes and Liquibase moves onto the next changeset, no matter how much time has passed. If the waiter reaches the maximum timeout, Liquibase throws an error. The default value is null (disabled).

The name of the DynamoDB API method that corresponds to this parameter is waitTimeout.

Note: This parameter doesn't guarantee exactly when DynamoDB terminates waiter requests. DynamoDB may time out early if it determines that the next retry would exceed the maximum wait time you specify.

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-waiter-update-total-timeout parameter controls the total amount of time the waiter spends before timing out:

  • If you want to allow DynamoDB to spend more time polling if necessary, set a higher value (longer timeout) or leave it at the default value of null (disabled). This may ensure that complex database operations have enough time to complete.
  • If you want DynamoDB to spend less time polling, set a lower value (shorter timeout). If you know your operations will complete quickly, this may reduce the overall latency of your application.

Syntax

You can set this parameter in the following ways:

Option Syntax
Liquibase properties file 
liquibase.dynamodb.waiter.update.totalTimeout: <int>
Global flow file argument (example) 
stages:
  Default:
    actions:
      - type: liquibase
        command: update
        globalArgs: { dynamodb-waiter-update-total-timeout: "<int>" }
Global CLI parameter 
liquibase
 --dynamodb-waiter-update-total-timeout=<int> update
 --changelog-file=example-changelog.xml

JVM system property (JAVA_OPTS Environment Variable)

 
JAVA_OPTS=-Dliquibase.dynamodb.waiter.update.totalTimeout=<int>
Liquibase Environment Variables 
LIQUIBASE_DYNAMODB_WAITER_UPDATE_TOTAL_TIMEOUT=<int>

For more information, see Working with Command Parameters.

Troubleshooting

If you reach the maximum wait time and the --dynamodb-waiters-fail-on-timeout parameter is set to true, Liquibase returns an exit code of 1 and displays the following message:

INFO: The maximum wait time configured in 'liquibase.dynamodb.waiter.update.totalTimeout' was reached and 'liquibase.dynamodb.waiters.failOnTimeout=true', so this job was aborted with a return code of 1. The DynamoDB process might have completed successfully, however, after the 'totalTimeout' was reached. It is a recommended practice to inspect the DynamoDb table for the results of the last changeset expected to run from this changelog. If these final changes are present in DynamoDB, please run 'liquibase changelogsync' to bring the DATABASECHANGELOG table into sync with the specified changelog.

Related links