An Akka Persistence Plugin for Mongo

A replicated Akka Persistence journal backed by MongoDB Casbah.

Prerequisites

Release

Technology	Version
Plugin
Scala	2.10.5, 2.11.7 - Cross Compiled
Akka	2.3.12 or higher
Mongo	2.6.x or higher

Snapshot

Technology	Version
Plugin
Scala	2.11.7
Akka	2.4.1 or higher
Mongo	3.1.x or higher

Installation

SBT

Release

resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/releases"

libraryDependencies ++= Seq(
  "com.github.ironfish" %% "akka-persistence-mongo-casbah"  % "0.7.6" % "compile")

Snapshot

resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"

libraryDependencies ++= Seq(
  "com.github.ironfish" %% "akka-persistence-mongo"  % "1.0.0-SNAPSHOT" % "compile")

Maven

Release

// Scala 2.10.5
<dependency>
    <groupId>com.github.ironfish</groupId>
    <artifactId>akka-persistence-mongo-casbah_2.10</artifactId>
    <version>0.7.6</version>
</dependency>

// Scala 2.11.7
<dependency>
    <groupId>com.github.ironfish</groupId>
    <artifactId>akka-persistence-mongo-casbah_2.11</artifactId>
    <version>0.7.6</version>
</dependency>

Snapshot

// Scala 2.11.7
<dependency>
    <groupId>com.github.ironfish</groupId>
    <artifactId>akka-persistence-mongo_2.11</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

Build Locally

You can build and install the plugin to your local Ivy cache. This requires sbt 0.13.8 or above.

sbt publishLocal

It can then be included as dependency:

libraryDependencies += "com.github.ironfish" %% "akka-persistence-mongo" % "1.0.0-SNAPSHOT"

Mongo Specific Details

Both the Journal and Snapshot configurations use the following Mongo components for connection management and write guarantees.

Mongo Connection String URI

The Mongo Connection String URI Format is used for establishing a connection to Mongo. Please note that while some of the components of the connection string are [optional] from a Mongo perspective, they are [required] for the Journal and Snapshot to function properly. Below are the required and optional components.

Standard URI connection scheme

mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][.collection][?options]]

Required

Optional

Mongo Write Concern

The Write Concern Specification describes the guarantee that MongoDB provides when reporting on the success of a write operation. The strength of the write concern determine the level of guarantee. When a PersistentActor's persist or persistAsync method completes successfully, a plugin must ensure the message or snapshot has persisted to the store. As a result, this plugin implementation enforces Mongo Journaling on all write concerns and requires all mongo instance(s) to enable journaling.

Journal Configuration

Activation

To activate the journal feature of the plugin, add the following line to your Akka application.conf. This will run the journal with its default settings.

akka.persistence.journal.plugin = "casbah-journal"

Connection

The default mongo-url is a string with a value of:

casbah-journal.mongo-url = "mongodb://localhost:27017/store.messages"

This value can be changed in the application.conf with the following key:

casbah-journal.mongo-url

# Example
casbah-journal.mongo-url = "mongodb://localhost:27017/employee.events"

See the Mongo Connection String URI section of this document for more information.

Write Concern

The default woption is an Integer with a value of:

casbah-journal.woption = 1

This value can be changed in the application.conf with the following key:

casbah-journal.woption

# Example
casbah-journal.woption = "majority"

Write Concern Timeout

The default wtimeout is an Long in milliseconds with a value of:

casbah-journal.wtimeout = 10000

This value can be changed in the application.conf with the following key:

casbah-journal.wtimeout

# Example
casbah-journal.wtimeout = 5000

See the Mongo Write Concern section of this document for more information.

Reject Non-Serializable Objects

This plugin supports the rejection of non-serializable journal messages. If reject-non-serializable-objects is set to true and a message is received who's payload cannot be serialized then it is rejected.

If set to false (the default value) then the non-serializable payload of the message becomes Array.empty[Byte] and is persisted.

the default reject-non-serializable-objects is a Boolean with the value of:

casbah-journal.reject-non-serializable-objects = false

This value can be changed in the application.conf with the following key:

casbah-journal.reject-non-serializable-objects

# Example
casbah-journal.reject-non-serializable-objects = true

Snapshot Configuration

Activation

To activate the snapshot feature of the plugin, add the following line to your Akka application.conf. This will run the snapshot-store with its default settings.

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

Connection

The default mongo-url is a string with a value of:

casbah-snapshot.mongo-url = "mongodb://localhost:27017/store.snapshots"

This value can be changed in the application.conf with the following key:

casbah-snapshot.mongo-url

# Example
casbah-snapshot.mongo-url = "mongodb://localhost:27017/employee.snapshots"

See the Mongo Connection String URI section of this document for more information.

Write Concern

The default woption is an Integer with a value of:

casbah-snapshot.woption = 1

This value can be changed in the application.conf with the following key:

casbah-snapshot.woption

# Example
casbah-snapshot.woption = "majority"

Write Concern Timeout

The default wtimeout is an Long in milliseconds with a value of:

casbah-snapshot.wtimeout = 10000

This value can be changed in the application.conf with the following key:

casbah-snapshot.wtimeout

# Example
casbah-snapshot.wtimeout = 5000

See the Mongo Write Concern section of this document for more information.

Snapshot Load Attempts

The snapshot feature of the plugin allows for the selection of the youngest of {n} snapshots that match an upper bound specified by configuration. This helps where a snapshot may not have persisted correctly because of a JVM crash. As a result an attempt to load the snapshot may fail but an older may succeed.

The default load-attempts is an Integer with a value of:

casbah-snapshot.load-attempts = 3

This value can be changed in the application.conf with the following key:

casbah-snapshot.load-attempts

# Example
casbah-snapshot.load-attempts = 5

Status

• All operations required by the Akka Persistence journal plugin API are supported.
• All operations required by the Akka Persistence Snapshot store plugin API are supported.
• Tested against Plugin TCK.
• Plugin uses Asynchronous Casbah Driver
• Message writes are batched to optimize throughput.

Performance

Minimal performance testing is included against a native instance. In general the journal will persist around 8,000 to 10,000 messages per second.

Sample Applications

The sample applications are now located in their own repository.

Change Log

1.0.0-SNAPSHOT

• Upgrade Akka 2.4.1.
• Upgrade Casbah to Async driver 3.1.
• Supports latest Plugin TCK.

0.7.6

• Upgrade sbt to 0.13.8.
• Upgrade Scala cross-compilation to 2.10.5 & 2.11.7.
• Upgrade Akka to 2.3.12.

0.7.5

• Upgrade sbt to 0.13.7.
• Upgrade Scala cross-compilation to 2.10.4 & 2.11.4.
• Upgrade Akka to 2.3.7.
• Examples moved to their own repository.
• Removed logback.xml in akka-persistence-mongo-casbah as it was not needed.
• Added pomOnly() resolution to casbah dependency, fixes #63.

0.7.4

• First release version to Maven Central Releases.
• Upgrade Sbt to 0.13.5.
• Upgrade Scala cross-compilation to 2.10.4 & 2.11.2.
• Upgrade Akka to 2.3.5.
• Added exception if /database or .collection are not accessible upon boot. Thanks @Fristi.
• Modified snapshot feature for custom serialization support. Thanks @remcobeckers.

0.7.3-SNAPSHOT

• Upgrade Sbt to 0.13.4.
• Upgrade Scala cross-compilation to 2.10.4 & 2.11.2.
• Upgrade Akka to 2.3.4.
• @deprecated write confirmations, CasbahJournal.writeConfirmations, in favor of AtLeastOnceDelivery.
• @deprecated delete messages, CasbahJournal.deleteMessages, per akka-persistence documentation.

Author / Maintainer

• Duncan DeVore (@ironfish)

Contributors

• Heiko Seeberger (@hseeberger)
• Sean Walsh (@SeanWalshEsq)
• Al Iacovella
• Remco Beckers
• Mark Fristi