Configuration

DynamoDB client configuration

Configuration for how to connect to DynamoDB is located under akka.persistence.dynamodb.client.

The default credentials provider will be used for authentication.

A local mode can be enabled, for testing with a DynamoDB local instance.

The following client settings be overridden in the client block:

sourceakka.persistence.dynamodb {
  client {
    # The amount of time to allow the client to complete the execution of an API call, including retry attempts.
    # It should be set lower than the circuit-breaker.call-timeout.
    call-timeout = 9 seconds

    # The amount of time to wait for each API request to complete before giving up and timing out.
    # Can be used together with `call-timeout` to enforce both a timeout on each individual HTTP request
    # (i.e. each retry) and the total time spent on all requests across retries (i.e. the 'API call' time).
    # Disabled when set to `off` or `none`.
    call-attempt-timeout = none

    # HTTP client settings.
    http {
      # Maximum number of allowed concurrent requests.
      max-concurrency = 50

      # The maximum number of pending acquires allowed.
      max-pending-connection-acquires = 10000

      # The amount of time to wait for a read before an exception is thrown.
      read-timeout = 30 seconds

      # The amount of time to wait for a write before an exception is thrown.
      write-timeout = 30 seconds

      # The amount of time to wait when initially establishing a connection before giving up and timing out.
      connection-timeout = 2 seconds

      # The amount of time to wait when acquiring a connection from the pool before giving up and timing out.
      connection-acquisition-timeout = 10 seconds

      # The maximum amount of time that a connection should be allowed to remain open, regardless of usage frequency.
      # Zero indicates an infinite amount of time.
      connection-time-to-live = 0

      # Configure whether idle connections in the connection pool should be closed.
      # Set `connection-max-idle-time` for amount of idle time that should be allowed.
      use-idle-connection-reaper = true

      # The maximum amount of time that a connection should be allowed to remain open while idle.
      # Enabled with `use-idle-connection-reaper`.
      connection-max-idle-time = 60 seconds

      # Configure the maximum amount of time that a TLS handshake is allowed to take.
      tls-negotiation-timeout = 5 seconds

      # Whether to enable or disable TCP KeepAlive.
      tcp-keep-alive = false
    }

    # Retry policy settings.
    retry-policy {
      # Whether retries are enabled.
      enabled = on

      # Set the retry mode. Can be `default`, `legacy`, `standard`, or `adaptive`.
      # See the documentation for the AWS SDK for Java for details.
      # As of AWS SDK 2.25.59, the default for DynamoDB is `legacy`, which is not recommended
      retry-mode = standard

      # Maximum number of times that a single request should be retried, assuming it fails for a retryable error.
      # Can be `default` for the default number of retries for the `retry-mode`, or override with a specific number.
      num-retries = default
    }

    # Request compression settings.
    compression {
      # Whether request compression is enabled.
      enabled = on

      # Minimum compression threshold, inclusive, in bytes. A request whose size is less than the threshold
      # will not be compressed. The value must be non-negative and no greater than 10 MiB (10,485,760 B).
      threshold = 10 KiB
    }

    # Configure the region of the DynamoDB instance.
    #
    # If this setting is not specified, then the default region lookup for the DynamoDB client will be used:
    #   - system property - `aws.region`
    #   - environment variable - `AWS_REGION`
    #   - credentials and config files at the default locations (~/.aws/credentials, ~/.aws/config)
    #   - if running in EC2, check the EC2 metadata service
    region = ""

    # Configuration for testing with DynamoDB local.
    # When enabled, will automatically set the endpoint, an arbitrary region, and dummy credentials.
    local {
      # Enable client for testing with DynamoDB local.
      enabled = false

      # Host for DynamoDB local endpoint.
      host = "localhost"

      # Port for DynamoDB local endpoint.
      port = 8000
    }
  }
}

Journal configuration

Journal configuration properties are by default defined under akka.persistence.dynamodb.journal.

See Journal plugin configuration.

Snapshot configuration

Snapshot store configuration properties are by default defined under akka.persistence.dynamodb.snapshot.

See Snapshot store plugin configuration.

Query configuration

Query configuration properties are by default defined under akka.persistence.dynamodb.query.

See Query plugin configuration.

Multiple plugins

To enable the DynamoDB plugins to be used by default, add the following lines to your application.conf:

sourceakka.persistence.journal.plugin = "akka.persistence.dynamodb.journal"
akka.persistence.snapshot-store.plugin = "akka.persistence.dynamodb.snapshot"

Note that all plugins have a shared root config section akka.persistence.dynamodb, which also contains the DynamoDB client configuration.

You can use additional plugins with different configuration. For example, a second configuration could be defined:

sourcesecond-dynamodb = $${akka.persistence.dynamodb}
second-dynamodb {
  client {
    # specific client settings here
  }
  journal {
    # specific journal settings here
  }
  snapshot {
    # specific snapshot settings here
  }
  query {
    # specific query settings here
  }
}

To use the additional plugin you would defineoverride the plugin id:

Java

sourcepublic class MyEntity extends EventSourcedBehavior<Command, Event, State> {
  @Override
  public String journalPluginId() {
    return "second-dynamodb.journal";
  }

  @Override
  public String snapshotPluginId() {
    return "second-dynamodb.snapshot";
  }
}

Scala

sourceEventSourcedBehavior(persistenceId, emptyState = State(), commandHandler, eventHandler)
  .withJournalPluginId("second-dynamodb.journal")
  .withSnapshotPluginId("second-dynamodb.snapshot")

For queries and projection SourceProvider you would use "second-dynamodb.query" instead of the default DynamoDBReadJournal.IdentifierDynamoDBReadJournal.Identifier() ("akka.persistence.dynamodb.query").

For additional details on multiple plugin configuration for projections see the Akka Projection DynamoDB docs.