This article covers at a very high level what’s needed to start exploring the Akka persistence plug-in when working together with Couchbase. It will also help you get a sample application running with Couchbase as a backend data store. If you’re new to Akka.Net, and/or Akka.Persistence we’ve written little story to help clarify what each component does. Otherwise if you’re more experienced, or short on time, skip the story to get the details of the Akka.Persistence.Couchbase plugin.

Our Story

We open with a few friends, Couchbase, Akka.Net, and Akka.Persistence. Couchbase was a guy that could store, and store, and store things, and never lose his ability to retrieve them back when needed quickly. Akka.Net was an expert at doing things lots of things at the same time. No matter how much he was doing, he could always add more. Finally, there was Akka.Persistence — he was always recording what Akka.Net was up to. He would take snapshots every now and then, whenever Akka.Net told him to, and send them over to a guy by the name of Akka.Persistence.MongoDB to package, so MongoDB (another guy who knew how to store things) could put them away for later. 

Alas, there was trouble in paradise. Couchbase was lonely. No one knew how to talk to him. He yearned to be able to help his community, but there was nothing he could do. The Great Engineer in the Sky, seeing his distress, decided it was time to create someone who could both understand Akka.Persistence and Couchbase. Before long, the Great Engineer created Akka.Persistence.Couchbase. She (we need a female in this whole thing) was wise, efficient, and most importantly, understood how to help Akka.Persistence and Couchbase work together. Soon, all of them were working together in harmony.

As you’ve gathered by now this is a story about how Akka.Persistence.Couchbase came into existence. 

This article intends to guide you on how to use Couchbase, Akka.Net, Akka.Persistence and Akka.Persistence.Couchbase together to create highly scalable applications. Let’s first spend a moment analyzing what each of these components bring to the table:

• Couchbase is an incredibly scalable document store. Most of all it supports N1QL which is a kind of SQL language for working against documents.
• Akka.Net is a toolkit and runtime for building highly concurrent, distributed, and fault tolerant event-driven applications on .NET & Mono. It is based on a message passing actor model paradigm just like Erlang, Akka(for Java), and Microsoft Orleans.
• Akka.Persistence is a plugin that allows you to:
  • Journal commands issued to your actor - which can later be used to restore the state of the actor.
  • Snapshot the state of your actor - which can be used to restore the state of an actor at a particular moment in time.
  • Akka.Persistence.Couchbase is another plugin that has a symbiotic relationship with Akka.Persistence. As we learned in the story above, its role is to memorialize, or retrieve journal or snapshots from Couchbase.

Why is this combination so useful? All these components bring to an application scalability, resilience, auditability and performance to the .NET world.  Many corporations have made heavy investments in .NET, so switching to other infrastructures such as Java and Erlang would be difficult to justify. In a future article, I will go into the details of why these components working together make sense.  For now let’s dig into how to make it work together.

To start with let me provide some background reference materials which will be useful in understanding, conceptually, how these components work:

• Akka System
• Akka.Persistence
• For a conceptual understanding of does this pluging works
• For a high-level tour of the code
• Couchbase SDK V2.2 - All you need to know about getting .Net to work with Couchbase

Each of these sites contains information on these components.

At a high level these are the steps you need to take to set-up your own development environment:

1. Download and install Couchbase 4.1 or higher.
2. Create a bucket using the administrative console and call it “akkatest”. This is where we will be storing the journal and snapshot entries.
3. Download the Akka.Persistence.Couchbase project.
4. You will need enable your Visual Studio to allow Nuget to restore all the necessary packages to your project.
5. Run the PersistenceSample project from within Visual Studio(2013 or higher).

Once you’ve completed these steps the sample application will have written some journal and snapshot entries into the “akkatest” bucket in Couchbase. Of course this is a very simple application developed by the guys at Akka.Net (thanks guys!). The goal is to show how to configure things to provide a springboard into your own development using these tools.

In follow-up articles I will put together some additional samples and descriptions as to why these components play nicely with each other.

If you have questions, add them in the comments below, or feel free to reach out to us.