A replicated Akka Persistence journal backed by MongoDB Casbah.
Technology | Version |
---|---|
Plugin | 0.7.5 |
Scala | 2.10.4, 2.11.4 - Cross Compiled |
Akka | 2.3.7 or higher |
Mongo | 2.6.x or higher |
Technology | Version |
---|---|
Plugin | 0.7.6-SNAPSHOT |
Scala | 2.10.4, 2.11.4 - Cross Compiled |
Akka | 2.3.7 or higher |
Mongo | 2.6.x or higher |
Due to the stability of the plugin and the increasing number of requests to publish to Maven Central Releases, we have implemented an official release strategy. In doing so, please note the following changes:
-
Starting with version
0.7.5-SNAPSHOT
The organization name has changed fromcom.github.ddevore
tocom.github.ironfish
. -
Versions
0.7.5
and beyond, when released, will be tagged and published tohttps://oss.sonatype.org/content/repositories/releases
. -
Snapshots will continue to be published to
https://oss.sonatype.org/content/repositories/snapshots
and use the version moniker#.#.#-SNAPSHOT
. -
When a snapshot is migrated to release, it will be tagged, published, and will no longer be available in the snapshots repository.
-
If your looking or the Sample Applications, they have been moved to their own repo.
Just standard release management stuff. Nothing to see here move along. :-)
resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/releases"
libraryDependencies ++= Seq(
"com.github.ironfish" %% "akka-persistence-mongo-casbah" % "0.7.5" % "compile")
resolvers += "Sonatype OSS Snapshots" at "https://oss.sonatype.org/content/repositories/snapshots"
libraryDependencies ++= Seq(
"com.github.ironfish" %% "akka-persistence-mongo-casbah" % "0.7.6-SNAPSHOT" % "compile")
// Scala 2.10.4
<dependency>
<groupId>com.github.ironfish</groupId>
<artifactId>akka-persistence-mongo-casbah_2.10</artifactId>
<version>0.7.5</version>
</dependency>
// Scala 2.11.4
<dependency>
<groupId>com.github.ironfish</groupId>
<artifactId>akka-persistence-mongo-casbah_2.11</artifactId>
<version>0.7.5</version>
</dependency>
// Scala 2.10.4
<dependency>
<groupId>com.github.ironfish</groupId>
<artifactId>akka-persistence-mongo-casbah_2.10</artifactId>
<version>0.7.6-SNAPSHOT</version>
</dependency>
// Scala 2.11.4
<dependency>
<groupId>com.github.ironfish</groupId>
<artifactId>akka-persistence-mongo-casbah_2.11</artifactId>
<version>0.7.6-SNAPSHOT</version>
</dependency>
You can build and install the plugin to your local Ivy cache. This requires sbt 0.13.5 or above.
sbt publishLocal
It can then be included as dependency:
libraryDependencies += "com.github.ironfish" %% "akka-persistence-mongo-casbah" % "0.7.6-SNAPSHOT"
Both the Journal and Snapshot configurations use the following Mongo components for connection management and write guarantees.
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.
mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][.collection][?options]]
Component | Description |
---|---|
mongodb:// |
The prefix to identify that this is a string in the standard connection format. |
host1 |
A server address to connect to. It is either a hostname, IP address, or UNIX domain socket. |
/database |
The name of the database to use. |
.collection |
The name of the collection to use. |
Component | Description |
---|---|
username:password@ |
If specified, the client will attempt to log in to the specific database using these credentials after connecting to the mongod instance. |
:port1 |
The default value is :27017 if not specified. |
hostN |
You can specify as many hosts as necessary. You would specify multiple hosts, for example, for connections to replica sets. |
:portN |
The default value is :27017 if not specified. |
?options |
Connection specific options. See Connection String Options for a full description of these options. |
Write concern describes the guarantee that MongoDB provides when reporting on the success of a write operation. The strength of the write concerns determine the level of guarantee. The following write concerns are supported.
Write Concern | Description |
---|---|
acknowledged |
[Safe] - Exceptions are raised for network issues and server errors; waits on a server for the write operation. |
journaled |
[JournalSafe] - Exceptions are raised for network issues, and server errors; the write operation waits for the server to group commit to the journal file on disk. |
replicas-acknowledged |
[ReplicasSafe] - Exceptions are raised for network issues and server errors; waits for at least 2 servers for the write operation. |
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"
The default mongo-journal-url
is a string
with a value of:
casbah-journal.mongo-journal-url = "mongodb://localhost:27017/store.messages"
This value can be changed in the application.conf
with the following key:
casbah-journal.mongo-journal-url
# Example
casbah-journal.mongo-journal-url = "mongodb://localhost:27017/employee.events"
See the Mongo Connection String URI section of this document for more information.
The default mongo-journal-write-concern
is a string
with a value of:
casbah-journal.mongo-journal-write-concern = "journaled"
This value can be changed in the application.conf
with the following key:
casbah-journal.mongo-journal-write-concern
# Example
casbah-journal.mongo-journal-write-concern = "replicas-acknowledged"
The default mongo-journal-write-concern-timeout
is an int
in milliseconds with a value of:
casbah-journal-mongo-journal-write-concern-timeout = 10000
This value can be changed in the application.conf
with the following key:
casbah-journal-mongo-journal-write-concern-timeout
# Example
casbah-journal-mongo-journal-write-concern-timeout = 5000
See the Mongo Write Concern section of this document for more information.
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-store"
The default mongo-snapshot-url
is a string
with a value of:
casbah-snapshot-store.mongo-snapshot-url = "mongodb://localhost:27017/store.snapshots"
This value can be changed in the application.conf
with the following key:
casbah-snapshot-store.mongo-snapshot-url
# Example
casbah-snapshot-store.mongo-snapshot-url = "mongodb://localhost:27017/employee.snapshots"
See the Mongo Connection String URI section of this document for more information.
The default mongo-snapshot-write-concern
is a string
with a value of:
casbah-snapshot-store.mongo-snapshot-write-concern = "journaled"
This value can be changed in the application.conf
with the following key:
casbah-snapshot-store.mongo-snapshot-write-concern
# Example
casbah-snapshot-store.mongo-snapshot-write-concern = "replicas-acknowledged"
See the Mongo Write Concern section of this document for more information.
The default mongo-snapshot-write-concern-timeout
is an int
in milliseconds with a value of:
casbah-snapshot-store.mongo-snapshot-write-concern-timeout = 10000
This value can be changed in the application.conf
with the following key:
casbah-snapshot-store.mongo-snapshot-write-concern-timeout
# Example
casbah-snapshot-store.mongo-snapshot-write-concern-timeout = 5000
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 mongo-snapshot-load-attempt
is an int
with a value of:
casbah-snapshot-store.mongo-snapshot-load-attempts = 3
This value can be changed in the application.conf
with the following key:
casbah-snapshot-store.mongo-snapshot-load-attempts
# Example
casbah-snapshot-store.mongo-snapshot-load-attempts = 5
- 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 Akka Persistence Test Kit version 0.3.4.
- Message writes are batched to optimize throughput.
AtLeastOnceDelivery
writes are batched to optimize throughput.- Mongo Sharding is not yet supported.
- Akka-Persistence is still considered experimental and as such the underlying api may change based on changes to Akka Persistence or user feedback.
Minimal performance testing is included against a native instance. In general the journal will persist around 8,000 to 10,000 messages per second.
The sample applications are now located in their own repository.
- 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
inakka-persistence-mongo-casbah
as it was not needed. - Added
pomOnly()
resolution tocasbah
dependency, fixes #63.
- 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.
- 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 ofAtLeastOnceDelivery
.@deprecated
delete messages,CasbahJournal.deleteMessages
, per akka-persistence documentation.