lerna-stack / akka-entity-replication   2.3.1

Apache License 2.0 GitHub

Akka extension for fast recovery from failure with replicating stateful entity on multiple nodes in Cluster

Scala versions: 2.13




If a node failure or network failure occurs, some entities in Cluster Sharding become unavailable and it will take more than 10 seconds to recover. akka-entity-replication provides fast recovery by creating replicas of entities in multiple locations and always synchronizing their status.

Each replicated entity is distributed across multiple nodes in the cluster like Cluster Sharding. This provides high scalability in addition to high availability.

akka-entity-replication helps to implement Event Sourcing and Command Query Responsibility Segregation (CQRS). Entity state updates are represented as events, and based on the events, a read model is updated for queries.

Requests recover (become green) immediately even if failure (kill a node) occurred

Technical background

Entity status synchronization is archived by Raft consensus algorithm. This algorithm ensures that the replica states of the entities are synchronized, so that if some failure occurs and a replica becomes unavailable, the other replicas can immediately continue processing.

The replicas of each entity are not started on every node in the Cluster but are placed in such a way that the load is distributed by sharding with akka-cluster-sharding. As nodes are added or removed, they are automatically rebalanced.

Akka ensures that the order of arrival of messages between source and destination is maintained. Note that if you send multiple messages, it is possible for entities to receive messages in a different order than they were sent, since the replicas of the entities in akka-entity-replication may be replaced in the course of sending messages.

Getting Started

To use this library, you must add a dependency into your sbt project, add the following lines to your build.sbt file:

Stable Release

Maven Central

⚠️ v2.0.0 contains breaking changes. For more details see CHANGELOG.

libraryDependencies += "com.lerna-stack" %% "akka-entity-replication" % "X.X.X"

Unstable Release (SNAPSHOT)

Sonatype Nexus (Snapshots)

resolvers += Resolver.sonatypeRepo("snapshots")  // If you use SNAPSHOT, you need to refer to Sonatype

libraryDependencies += "com.lerna-stack" %% "akka-entity-replication" % "X.X.X-SNAPSHOT"

These versions of akka-entity-replication depends on Akka 2.6.x. It has been published for Scala 2.13. akka-entity-replication is tested with OpenJDK8 and OpenJDK11.

NOTE: akka-entity-replication uses Akka's internal API. It is recommended that you use the same version of Akka as akka-entity-replication for your application to avoid compatibility issues. Please see build.sbt for the version of Akka that akka-entity-replication depends on.

For more information on how to implement an application using this library, please refer to the following documents.

NOTE: It is highly recommended that you carefully do cluster operations. For more details, please refer to Operation Guide.

Rollback tool

Rollback tool akka-entity-replication-rollback-tool-cassandra is helpful for rolling back Raft shards of akka-entity-replication. You can use this rollback tool if your application uses Akka Persistence Cassandra. Add the following likes to your build.sbt file to use this rollback tool:

Stable Release

Maven Central

libraryDependencies += "com.lerna-stack" %% "akka-entity-replication-rollback-tool-cassandra" % "X.X.X"

Unstable Release (SNAPSHOT)

Sonatype Nexus (Snapshots)

resolvers += Resolver.sonatypeRepo("snapshots")  // If you use SNAPSHOT, you need to refer to Sonatype

libraryDependencies += "com.lerna-stack" %% "akka-entity-replication-rollback-tool-cassandra" % "X.X.X-SNAPSHOT"

Please refer to Rollback Guide for more details.

Since the rollback tool depends on some internal APIs, it is recommended that you use the following versions to avoid binary compatibility issues:

  • The same version of akka-entity-replication as the one your application uses
  • The same version of akka-persistence-cassandra as the one on which this rollback tool depends

Please see build.sbt for reviewing the library versions on which this rollback tool depends on.

For Contributors

CONTRIBUTING may help us.

For Maintainers

RELEASING describes how to release a new version.


You can see a sample application using this extension in the following project.



You can see all the notable changes in CHANGELOG.

Migration Guide

Migration Guide describes how to migrate code and settings from previous versions.


akka-entity-replication is released under the terms of the Apache License Version 2.0.

* The names of the companies and products described in this site are trademarks or registered trademarks of the respective companies.
* Akka is a trademark of Lightbend, Inc.

© 2020 TIS Inc.