Schema Evolutions

Hello, we are using Lagom 1.4.15 with Scala 2.12.8 and Cassandra. We’ve made a few changes to our domain model classes, which does not affect Cassandra table structure, but the JSON which is being stored for Events will change. I’ve followed the documentation for Schema Evolution, but my doubts are -

  • When does this schema evolution run?
  • Do we have to run it manually, or is it all automatic (during runtime)?
  • Using this technique, will the new and old events be able to coexist?


Hi @mmwaikar,

message migration happens any time a message is deserialized. That may be:

  1. when a node with the new codebase receives a command or response produced by an old node in the cluster
  2. when reading an event or a snapshot from the database

Case 1. happens during a very short period of time when doing a rolling update. The most common case, then, is case 2..

Events and snapshots are stored immutably on the database so, as the code evolves, new code needs to be able to read content produced by old code. Every data stored in the database includes a manifest metadata field detailing the type and revision (aka evolution). So, if you try to read a BankAccount of revision 4 but the database provides a BankAccount of revision 2, the internals will locate the necessary migrations and upcast the data read to a revision 4 applying your conversions.
Then, your running Persistent Entity will get a BankAccount of revision 4 and not know the actual data on the DB is a different format. Any new event emitted using that version of your code will have the manifest metadata indicating it’s BankAccount version 4. To answer your question: all this conversion happens automatically.

Finally, this whole process will only work as long as you keep a collection of migrations capable of upcasting any existing event to the most recent modelling.