Getting Started

Dependencies

The Akka dependencies are available from Akka’s library repository. To access them there, you need to configure the URL for this repository.

Maven

<project>
  ...
  <repositories>
    <repository>
      <id>akka-repository</id>
      <name>Akka library repository</name>
      <url>https://repo.akka.io/maven</url>
    </repository>
  </repositories>
</project>

sbt

resolvers += "Akka library repository".at("https://repo.akka.io/maven")

Gradle

repositories {
    mavenCentral()
    maven {
        url "https://repo.akka.io/maven"
    }
}

Additionally, add the dependency as below.

Maven

<properties>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>com.lightbend.akka</groupId>
    <artifactId>akka-persistence-dynamodb_${scala.binary.version}</artifactId>
    <version>2.0.4</version>
  </dependency>
</dependencies>

sbt

libraryDependencies += "com.lightbend.akka" %% "akka-persistence-dynamodb" % "2.0.4"

Gradle

def versions = [
  ScalaBinary: "2.13"
]
dependencies {
  implementation "com.lightbend.akka:akka-persistence-dynamodb_${versions.ScalaBinary}:2.0.4"
}

This plugin depends on Akka 2.10.0 or later, and note that it is important that all akka-* dependencies are in the same version, so it is recommended to depend on them explicitly to avoid problems with transient dependencies causing an unlucky mix of versions.

The plugin is published for Scala 2.13 and 3.3.

Enabling

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

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

More information about each individual plugin in:

Local testing with docker

DynamoDB local can be run in Docker. Here’s an example docker compose file:

sourceversion: '3.8'
services:
  dynamodb-local:
    command: "-jar DynamoDBLocal.jar -sharedDb -inMemory"
    image: "amazon/dynamodb-local:latest"
    container_name: dynamodb-local
    ports:
      - "8000:8000"
    working_dir: /home/dynamodblocal

Start with:

docker compose -f docker/docker-compose.yml up

Client local mode

The DynamoDB client can be configured with a local mode, for testing with DynamoDB local:

sourceakka.persistence.dynamodb {
  client.local.enabled = true
}

Creating tables locally

A CreateTablesCreateTables utility is provided for creating tables locally:

Java

sourceimport akka.persistence.dynamodb.DynamoDBSettings;
import akka.persistence.dynamodb.util.ClientProvider;
import akka.persistence.dynamodb.util.javadsl.CreateTables;
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient;

String dynamoDBConfigPath = "akka.persistence.dynamodb";
String dynamoDBClientConfigPath = dynamoDBConfigPath + ".client";

DynamoDBSettings settings =
    DynamoDBSettings.create(system.settings().config().getConfig(dynamoDBConfigPath));

DynamoDbAsyncClient client = ClientProvider.get(system).clientFor(dynamoDBClientConfigPath);

// create journal table, synchronously
CreateTables.createJournalTable(system, settings, client, /*deleteIfExists:*/ true)
    .toCompletableFuture()
    .get(10, TimeUnit.SECONDS);

// create snapshot table, synchronously
CreateTables.createSnapshotsTable(system, settings, client, /*deleteIfExists:*/ true)
    .toCompletableFuture()
    .get(10, TimeUnit.SECONDS);

Scala

sourceimport akka.persistence.dynamodb.DynamoDBSettings
import akka.persistence.dynamodb.util.ClientProvider
import akka.persistence.dynamodb.util.scaladsl.CreateTables
import software.amazon.awssdk.services.dynamodb.DynamoDbAsyncClient

val dynamoDBConfigPath = "akka.persistence.dynamodb"
val dynamoDBClientConfigPath = dynamoDBConfigPath + ".client"

val settings: DynamoDBSettings = DynamoDBSettings(system.settings.config.getConfig(dynamoDBConfigPath))
val client: DynamoDbAsyncClient = ClientProvider(system).clientFor(dynamoDBClientConfigPath)

// create journal table, synchronously
Await.result(CreateTables.createJournalTable(system, settings, client, deleteIfExists = true), 10.seconds)

// create snapshot table, synchronously
Await.result(CreateTables.createSnapshotsTable(system, settings, client, deleteIfExists = true), 10.seconds)

See the table definitions in the individual plugins for more information on the tables that are required: