It was just about 10 years ago when we shipped Akka.NET v1.0.2, the release where we first introduced betas of some of our most popular Akka.Persistence plugins: Akka.Persistence.Postgres, Akka.Persistence.SqlServer, and Akka.Persistence.Sqlite.

All of these plugins were based off of a shared ADO.NET Akka.Persistence architecture called Akka.Persistence.Sql.Common and this architecture has served both us and our users / customers well over the past 10 years, somewhere to the tune of 1.6 million installations!

But, as of Akka.NET v1.5.40 these plugins are all deprecated in favor of Akka.Persistence.Sql - the successor plugin for all SQL RDBMS we introduced along with the release of Akka.NET v1.5.

In the next sections we’ll explain our decision along with showing you our migration guide for moving off any of the affected Akka.Persistence.Sql.Common plugins and onto Akka.Persistence.Sql.

Why Retire Akka.Persistence.Sql.Common?

Back in 2015 Akka.NET was much more of a community-driven effort than a professionally-driven one that it is today - this is how most large OSS projects begin.

There’s a cycle that comes with open source projects as they mature:

In the early stages of a open source project less is known about the constraints and matters that heavy end-users are going to care about, because those heavy end-user use cases don’t yet exist. Therefore there are no significant external forces to drive quality controls such as backwards compatibility, developer experience, performance, etc - at this early stage all of the motivating factors are very much internal, driven by the contributors themselves.

Akka.Persistence.Sql.Common and the Akka.Persistence.TCK are good examples of this - we had a well-defined standard for programming against ADO.NET for any compatible T-SQL database and we had a well defined testing and verification plugin that could ensure a degree of compliance with the Akka.Persistence behavioral specifications. That looks pretty darn good on the surface.

But here’s the tricky part with community contributions: community contributors leave and the maintainers who stick around inherit those decisions, warts and all.

This is precisely what happened with the Akka.Persistence.Sql.Common plugins over the years - we’ve had to spend thousands of man-hours troubleshooting:

1. Inconsistent and error-prone serialization implementations across all Akka.Persistence plugins;
2. Some plugins, like Akka.Persistence.SqlServer, support Akka.Persistence’s anti-corruption layer whereas others, such as Akka.Persistence.PostgreSql, do not;
3. Akka.Persistence.Query was implemented somewhat hapazardly across all of these plugins; and
4. Some of them even supported totally different and conflicting schema, such as whether or not the Metadata table for tracking SeqNrs for deleted entities was used or not.

Even with all of the tooling that the early Akka.NET community originally created to help standardize these plugins, we still ended up with a bunch of diverse behavior at the edges of their use - and this resulted in wide divergences in terms of plugin performance, data consistency, ease of use, and more. All of this adds up to quite a support burden for the Petabridge team, as we’re the ones who’ve maintained it largely by ourselves for the past 8-9 years.

In order to reduce our total cost of ownership, we’re retiring these plugins and are no longer going to be patching them. It’s time to move your workloads over to Akka.Persistence.Sql (itself, originally a community contribution!). We announced we were going to make this change back in 2023. It’s time.

Akka.Persistence.Sql Benefits and Migration Guide

What are the benefits of Akka.Persistence.Sql?

Performance

Well for starters, Akka.Persistence.Sql vastly outperforms its predecessor plugins by a significant margin. You can view our performance comparison for SQL Server here.

Or you can grok this issue opened by an end-user comparing their experiences between Akka.Persistence.Sql and Akka.Persistence.SqlServer if you’d like a report directly from the field: Performance report on Akka.Persistence.Sql vs Akka.Persistence.SqlServer.

Consistently Great Experience Across Databases

Akka.Persistence.Sql imposes a truly unified persistence model on all RDBMS architectures. The anti-corruption layer is there. We use the correct indices everywhere. We handle deletes appropriately and consistently across all use cases. It “just works.”

Efficient Akka.Persistence.Query

Probably the biggest change we made, structurally, to the schema of Akka.Persistence.Sql is the creation of a dedicated table for “tagged” queries - this is a secondary index we can use for scanning events in an aspect-oriented fashion, rather than an entity-specific one. If you want to consume all of the “PaymentProcessed” events from all “Payment” entities, tags are a great way of facilitating that.

One major problem the original Akka.Persistence.Sql.Common design suffered from, however, was that these types of queries require a full table scan and then string.Contains calls on a comma-delimited tags field on each record. This approach doesn’t scale very well once your journal size exceeds 10 million rows or so.

In Akka.Persistence.Sql we use covered indicies and are able to perform these tagged queries very efficiently.

Backwards Compatibility

Since Akka.Persistence.Sql follows our more mature and professional standards, one of the things we’ve done is ensure full backwards compatibility with the Akka.Persistence.Sql.Common schema and / or a migration path to transfer to the Akka.Persistence.Sql schema instead (which you’ll need to do in order to take advantage of tagged query performance and the anti-corruption layer.)

Akka.Persistence.Sql Migration Process

First and foremost, watch our video “Akka.Persistence.Sql Upgrade and Migration Guide”

Second, please see the written resources we’ve prepared for migrating:

• Migration Guide:
  Learn the necessary steps to upgrade by following the Migration Guide.

• Migration Walkthrough:
  For a step-by-step walkthrough, check out our Migration Walkthrough.

We’ve had hundreds of users complete this migration process over the past 18 months, some with journal sizes measuring billions of rows. It’s a well-tested and well-trodden path.

Parting Thoughts on Community Contributions to Akka.NET

I don’t want to make this post sound like the Petabridge team is “down” on community contributions. Of course not - one of the major AOT features of Akka.NET v1.6 we just merged in was contributed by one of our own customers.

The difference is that over the past several years we’ve had to set high standards for contributing to Akka.NET, documented here: “Contributing to Akka.NET”. We work with our contributors to help make sure they meet these standards.

Contributing to a high-standards open source software is a great way to skill yourself up and learn a lot about how to set high standards for your own individual work, projects, and organizations. And there are always opportunities for contributions within the Akka.NET ecosystem - hop into the #contributors room in the Akka.NET Discord and ask if you need help getting started.

If you liked this post, you can share it with your followers or follow us on Twitter!