Migration Guide Eventsourced to Akka Persistence 2.3.x

Migration Guide Eventsourced to Akka Persistence 2.3.x

General notes

Eventsourced and Akka Persistence share many high-level concepts but strongly differ on design, implementation and usage level. This migration guide is more a higher-level comparison of Eventsourced and Akka Persistence rather than a sequence of low-level instructions how to transform Eventsourced application code into Akka Persistence application code. This should provide a good starting point for a migration effort. Development teams should consult the user documentation of both projects for further details.

Scope of this migration guide is code migration, not journal migration. Journals written by Eventsourced can neither be used directly Akka Persistence nor migrated to Akka Persistence compatible journals. Journal migration tools may be provided in the future but do not exist at the moment.


Eventsourced and Akka Persistence are both Akka Extensions.

Eventsourced: EventsourcingExtension

  • Must be explicitly created with an actor system and an application-defined journal actor as arguments. (see example usage).
  • Processors and Channels must be created with the factory methods processorOf and channelOf defined on EventsourcingExtension.
  • Is a central registry of created processors and channels.

Akka Persistence: Persistence extension

  • Must not be explicitly created by an application. A Persistence extension is implicitly created upon first processor or channel creation. Journal actors are automatically created from a journal plugin configuration (see Journal plugin API).
  • Processors and Channels can be created like any other actor with actorOf without using the Persistence extension.
  • Is not a central registry of processors and channels.


Eventsourced: Eventsourced

  • Stackable trait that adds journaling (write-ahead-logging) to actors (see processor definition and creation). Name Eventsourced caused some confusion in the past as many examples used Eventsourced processors for command sourcing. See also this FAQ entry for clarification.
  • Must be explicitly recovered using recovery methods on EventsourcingExtension. Applications are responsible for avoiding an interference of replayed messages and new messages i.e. applications have to explicitly wait for recovery to complete. Recovery on processor re-start is not supported out-of-the box.
  • Journaling-preserving behavior changes are only possible with special-purpose methods become and unbecome, in addition to non-journaling-preserving behavior changes with default methods context.become and context.unbecome.
  • Writes messages of type Message to the journal (see processor usage). Sender references are not stored in the journal i.e. the sender reference of a replayed message is always system.deadLetters.
  • Supports snapshots.
  • Identifiers are of type Int and must be application-defined.
  • Does not support batch-writes of messages to the journal.
  • Does not support stashing of messages.

Akka Persistence: Processor

  • Trait that adds journaling (write-ahead-logging) to actors (see Processors) and used by applications for command sourcing. Corresponds to Eventsourced processors in Eventsourced but is not a stackable trait.
  • Automatically recovers on start and re-start, by default. Recovery can be customized or turned off by overriding actor life cycle hooks preStart and preRestart. Processor takes care that new messages never interfere with replayed messages. New messages are internally buffered until recovery completes.
  • No special-purpose behavior change methods. Default behavior change methods context.become and context.unbecome can be used and are journaling-preserving.
  • Writes messages of type Persistent to the journal (see Persistent messages). Corresponds to Message in Eventsourced. Sender references are written to the journal. A reply to senders must therefore be done via a channel in order to avoid redundant replies during replay. Sender references of type PromiseActorRef are not journaled, they are system.deadLetters on replay.
  • Supports Snapshots.
  • Identifiers are of type String, have a default value and can be overridden by applications.
  • Supports Batch writes.
  • Supports stashing of messages.

Akka Persistence: EventsourcedProcessor

  • Extension trait and pattern on top of Processor to support Event sourcing. Has no direct counterpart in Eventsourced. Can be considered as a replacement of two processors in Eventsourced where one processor processes commands and the other processes events that have been emitted by the command processor.


Eventsourced: DefaultChannel

  • Prevents redundant delivery of messages to a destination (see usage example and default channel).
  • Is associated with a single destination actor reference. A new incarnation of the destination is not automatically resolved by the channel. In this case a new channel must be created.
  • Must be explicitly activated using methods deliver or recover defined on EventsourcingExtension.
  • Must be activated after all processors have been activated. Depending on the recovery method, this is either done automatically or must be followed by the application (see non-blocking recovery). This is necessary for a network of processors and channels to recover consistently.
  • Does not redeliver messages on missing or negative delivery confirmation.
  • Cannot be used standalone.

Akka Persistence: Channel

  • Prevents redundant delivery of messages to a destination (see Channels) i.e. serves the same primary purpose as in Eventsourced.
  • Is not associated with a single destination. A destination can be specified with each Deliver request and is referred to by an actor path. A destination path is resolved to the current destination incarnation during delivery (via actorSelection).
  • Must not be explicitly activated. Also, a network of processors and channels automatically recover consistently, even if they are distributed. This enhancement, together with improved processor recovery, makes recovery of complex Akka Persistence applications trivial. No special recovery procedures must be run by applications.
  • Redelivers messages on missing delivery confirmation (see Message re-delivery). In contrast to Eventsourced, Akka Persistence doesn't distinguish between missing and negative confirmations. It only has a notion of missing confirmations using timeouts (which are closely related to negative confirmations as both trigger message redelivery).
  • Can be used standalone.

Persistent channels

Eventsourced: ReliableChannel

  • Provides DefaultChannel functionality plus persistence and recovery from sender JVM crashes (see ReliableChannel). Also provides message redelivery in case of missing or negative delivery confirmations.
  • Delivers next message to a destination only if previous message has been successfully delivered (flow control is done by destination).
  • Stops itself when the maximum number of redelivery attempts has been reached.
  • Cannot reply on persistence.
  • Can be used standalone.

Akka Persistence: PersistentChannel

  • Provides Channel functionality plus persistence and recovery from sender JVM crashes (see Persistent channels). Same message redelivery features as Channel.
  • Redelivers unconfirmed messages concurrently to newly delivered messages. Flow control is done by channel using a configurable minimum and maximum number of pending confirmations.
  • Optionally notifies applications about messages for which the maximum number of delivery attempts has been reached (also offered by Channel).
  • Can reply on persistence (= accept acknowledgement).
  • Can be used standalone.



  • No direct support for views. Only way to maintain a view is to use a channel and a processor as destination.

Akka Persistence: View

  • Receives the message stream written by a Processor or EventsourcedProcessor by reading it directly from the journal (see Views). Alternative to using channels. Useful in situations where actors shall receive a persistent message stream in correct order without duplicates.
  • Can be used in combination with Channels for sending messages.
  • Supports Snapshots.



  • Uses a protobuf serializer for serializing Message objects.
  • Delegates to a configurable Akka serializer for serializing Message payloads.
  • Delegates to a configurable, proprietary (stream) serializer for serializing snapshots.
  • See Serialization.

Akka Persistence:

  • Uses a protobuf serializer for serializing Persistent objects.
  • Delegates to a configurable Akka serializer for serializing Persistent payloads.
  • Delegates to a configurable Akka serializer for serializing snapshots.
  • See Custom serialization.

Sequence numbers


  • Generated on a per-journal basis.

Akka Persistence:

  • Generated on a per-processor basis.

Storage plugins


Akka Persistence:

  • Plugin API: SyncWriteJournal, AsyncWriteJournal, AsyncRecovery, SnapshotStore (see Storage plugins).
  • Clear separation between journal and snapshot storage plugins.
  • Limited number of Pre-packaged plugins (LevelDB journal and local snapshot store).
  • Impressive list of community plugins.