Migrating Axon 2.x to 3.x

Hi all.

In my current job we have conflicting views about the use of Axon in the future, we have our fair share of problems with it, like

a) problem we have in our daily operation like concurrency issues and event order guarantee and other time-based issues,

but also about more architectural concerns, like

b) having distributed command bus with guaranteed delivery, scaling the app horizontally with sourced events and having distributed events across clusters (see [1], [2] and [3] below).

At the moment it seems the only supporter of Axon it’s me, even if the a) problems are giving me much headaches, but also very worried about the b) issues if we decided to go ahead with Axon.

So my questions are:

  1. does Axon 3 deals with the a) concerns?
  2. does Axon 3 deals with the b) concerns?
  3. is there a upgrade route or guide, or will we have to practically rewrite the entire application?
  4. does someone have experience with a migration like that?

Thanks in advance.

[1] https://groups.google.com/d/msg/axonframework/l6ps2ZlOiMA/WcVLmiucDgAJ
[2] https://groups.google.com/d/msg/axonframework/Gp1rKpokXIA/pGLwXMWzDQAJ
[3] https://groups.google.com/d/msg/axonframework/PS4dxeBrm64/MihWsx80DwAJ

Hi António,

I hope I can take away some of you and your teams concerns with this reply.
Let’s move through them point wise to break it down nicely:

  1. does Axon 3 deals with the a) concerns?

This is actually three questions rather than one, so let me provide a further break down.

1.a) concurrency issues
For the first bit of concern a, I’d need to know where you’re experiencing concurrency issues prior to being able to tell whether Axon Framework 3 resolves this. What I’m mostly looking for is whether this is an issue for command processing/handling or event processing/handling.
1.b) event order guarantee
The event handling order in Axon 3 is guaranteed through means of a global index which is set on each event. Thus, when events are supplied in a subscribing or tracking manor, they will flow in order. Out-of-order events might occur when JDBC is in play, is the insert order might differ from the commit order of your events. To that end, Axon stores a token to keep track of how far it is in handling the events from your EventStore, which also contains any gaps in your system.
So yes, I’d say that Axon 3 does handle this concern.

1.c) other time-based issues
As well as with the 'concurrency issues` point in 1.a, ‘other time-based issues’ is also a little vague. So a little background on this specific point would be much appreciated. If this request is restricted to the event side of things, I’d say that my reply on (1.b) holds here as well.

Taken as a whole though, the ‘global concern’ in point 1 seem to refer to event publishing/processing in general. There are several safety guards in place (as mentioned in 1.b), but to provide more certainty in this space for large scale applications, it might be worth considering AxonDB.

  1. does Axon 3 deals with the b) concerns?

I’d say this is also a three part question, so I’ll again chop it up into several parts as I did with (1).
2.a) Distributed Command Bus with guaranteed delivery
As pointed out in Allard’s reply on the forum you’ve shared, a sensible retry mechanism on a command would be what I’d recommend. As it is hard to provide a one off solution for any use case, setting up such a retry mechanism is left for the users, as we deem that the current scenario is a sensible default.

On another note, users typically have/had doubts when using JGroups to distribute the CommandBus. Therefor we introduce a Spring Cloud solution for the DistributedCommandBus into the framework. This enables you to select your own Spring Cloud implementation to figure out the routing of your nodes, thus enabling you to use Consul, Eureka and Zookeeper for example.

Additionally, AxonHub is also very good solution to distributing your commands throughout your cluster, as this product is tailored to providing you the best way to distributing your messages.

Lastly, are there any other points from the post [1] which you’re still concerned about? I am however leaning to the point that yes, Axon 3 does alleviate this concern to some extent.

2.b) Replaying Events on a Cluster
In this point we’re referring to a situation where you’ve got several EventStores populating the same query model and you want to do a replay. This means you have a Event Processors in your system which pulls events from several sources at once. Axon 3 does allow you with simpler interfaces to support such a set up so that the event are pulled in the right order. This is built-yourself for now however. We do see this as a feature which will be added into the framework, as it is something we’re working on.

Lastly, like pointed out earlier, our product AxonDB might be a quicker solution to the problem in this space.

Concluding I’d state that yes, Axon 3 comes a long way in solving the problem at hand.

2.c) Scaling horizontally with sourced events
I’d summarize Alessadro’s concern in post [3] to state that he is trying to figure out how to correctly ensure that event, sagas and query models are correctly persisted to every node in the cluster, with the big caveat that every node has a dedicated data source. Nothing in Axon 3 has changed apposed to Axon 2 which changes the comments which Allard and Rene placed on Alessadro’s concern. As such, the suggested course of action, being consistent routing of commands for a given aggregate to the same instance and having a single source of truth regarding the event store, is what I would recommend as well for a CQRS/ES application.

If you want to have additional certainty in regards to EventStore availability, I’d recommend introducing a master-slave system for you store, with at least 2 slave EventStores and one master store. This is exactly what AxonDB will do under the cover to ensure that your events will be persisted and that they are replicated and available.

  1. is there a upgrade route or guide, or will we have to practically rewrite the entire application?

The reference guide currently does not provide a migration guide, although we at AxonIQ do see the benefit of this. Additionally, we’re more than happy to provide you with some support (or hands) to convert an Axon 2 application to Axon 3.

  1. does someone have experience with a migration like that?

I have experience with such a migration. I can ensure you that code wise the adjustment isn’t to harsh. Of course some implementations have changed internally. You for example no longer extend from an AbstractSaga or AbstractAggregate, but use annotation as well. Additionally, the notion of Event Clusters is replaced for Event Processors in two different flavors (Subscribing and Tracking). However probably the most intricate part of this process is updating your EventStore to introduce the global index I’ve been referring to earlier on every event entry.

I feel like I’ve pointed out AxonDb and AxonHub quite a lot without thoroughly explaining how they work.
As this post is already quite long, instead of typing away, I’d like to refer to the following videos for some additional background on the topic:

  • AxonDB explanation
  • AxonHub explanation
  • Showcase of splitting up of a micro service Axon application using AxonHub and AxonDB.

Hope this gives you some insight to alleviate your concerns António.

And I hope I’ll hear form you (and your team?) in the future too!

Would be sad to see you leave from this forum if you’d decided against using Axon Framework.



For us the biggest change in Axon 3 was the way things are configured. In Axon 2.x you have the spring xml configuration with custom namespaces which is nice, compact and understandable, it helps to see how things fit together. In Axon 3 the configurationexperience is a lot less straight forward, and the documentation - in all fairness - is much less elaborate than it was for 2.x. Understanding how the new configuration mechanism works accounted to about half of the time spent on migration, I felt that it should not have been this way.


Hi Steven, that’s too much information for me to crunch :slight_smile: I will have to do it in due time, probably when/if we are close to decide what to do…

Thanks a lot for all the info.


Hi Jorg, can you elaborate a little further? We actually didn’t used any XML, we configured everything either by using the Spring Boot auto-configuration or by using the JavaConfig configurations.

So when you say “new configuration mechanism” what specifically are you talking about? Java specific configurations like the ones done by JavaConfig, or something Axon specific?

Thanks for your input.


Yes that’s what I meant, the 2.x xml namespace is easier to navigate and see how things fit together. Spring autoconfig can get quite obscure if you’re not familiar with the specific library.