Snapshot store plugin

The snapshot plugin enables storing and loading snapshots for event sourced persistent actors.

Tables

The snapshot plugin requires a snapshot table to be created in DynamoDB. The default table name is snapshot and this can be configured (see the reference configuration for all settings). The table should be created with the following attributes and key schema:

Read capacity units should be based on expected entity recoveries. Write capacity units should be based on expected rates for persisting snapshots.

An example aws CLI command for creating the snapshot table:

copysourceaws dynamodb create-table \
  --table-name snapshot \
  --attribute-definitions \
      AttributeName=pid,AttributeType=S \
  --key-schema \
      AttributeName=pid,KeyType=HASH \
  --provisioned-throughput \
      ReadCapacityUnits=5,WriteCapacityUnits=5

Indexes

If start-from-snapshot queries are being used, then a global secondary index needs to be added to the snapshot table, to index snapshots by slice. The default name (derived from the configured table name) for the secondary index is snapshot_slice_idx and may be explicitly set (see the reference configuration). The following attribute definitions should be added to the snapshot table, with key schema for the snapshot slice index:

Write capacity units for the index should be aligned with the snapshot table. Read capacity units should be based on expected queries.

An example aws CLI command for creating the snapshot table and slice index:

copysourceaws dynamodb create-table \
  --table-name snapshot \
  --attribute-definitions \
      AttributeName=pid,AttributeType=S \
      AttributeName=entity_type_slice,AttributeType=S \
      AttributeName=event_timestamp,AttributeType=N \
  --key-schema \
      AttributeName=pid,KeyType=HASH \
  --provisioned-throughput \
      ReadCapacityUnits=5,WriteCapacityUnits=5 \
  --global-secondary-indexes \
    '[
       {
         "IndexName": "snapshot_slice_idx",
         "KeySchema": [
           {"AttributeName": "entity_type_slice", "KeyType": "HASH"},
           {"AttributeName": "event_timestamp", "KeyType": "RANGE"}
         ],
         "Projection": {
           "ProjectionType": "ALL"
         },
         "ProvisionedThroughput": {
           "ReadCapacityUnits": 5,
           "WriteCapacityUnits": 5
         }
      }
    ]'

Creating tables locally

For creating tables with DynamoDB local for testing, see the CreateTables utility.

Configuration

To enable the snapshot plugin to be used by default, add the following line to your Akka application.conf:

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

It can also be enabled with the snapshotPluginId for a specific EventSourcedBehavior and multiple plugin configurations are supported.

Reference configuration

The following can be overridden in your application.conf for the snapshot specific settings:

copysourceakka.persistence.dynamodb {
  snapshot {
    class = "akka.persistence.dynamodb.snapshot.DynamoDBSnapshotStore"

    # name of the table to use for snapshots
    table = "snapshot"

    # Name of global secondary index to support queries and/or projections.
    # "" is the default and denotes an index named "${table}_slice_idx"
    # (viz. when table (see above) is "event_journal", the GSI will be
    # "event_journal_slice_idx").  If for some reason an alternative GSI name
    # is required, set that GSI name explicitly here; if set explicitly, this
    # name will be used unmodified
    by-slice-idx = ""

    # Enables an optimization in Akka for avoiding snapshot deletes in retention.
    only-one-snapshot = true
  }
}

Usage

The snapshot plugin is used whenever a snapshot write is triggered through the Akka Persistence APIs.

Snapshot serialization

The state is serialized with Akka Serialization and the binary snapshot representation is stored in the snapshot column together with information about what serializer that was used in the ser_id and ser_manifest columns.

Retention

The DynamoDB snapshot plugin only ever keeps one snapshot per persistence id in the database. If a keepNSnapshots > 1 is specified for an EventSourcedBehavior that setting will be ignored.