= Distributed James Server &mdash; Cassandra migration
:navtitle: Cassandra migration

Cassandra upgrades implies the creation of a new table. Thus restarting James is needed, as new tables are created on restart.

Once done, we ship code that tries to read from new tables, and if not possible backs up to old tables. You can thus safely run
without running additional migrations.

On the fly migration can be enabled. However, one might want to force the migration in a controlled fashion, and update
automatically current schema version used (assess in the database old versions is no more used, as the corresponding tables are empty).
Note that this process is safe: we ensure the service is not running concurrently on this James instance, that it does not bump
version upon partial failures, that race condition in version upgrades will be idempotent, etc...

These schema updates can be triggered by xref:distributed/operate/webadmin.adoc#_cassandra_schema_upgrades[webadmin].

Note that currently the progress can be tracked by logs.

Here are the implemented migrations:

* *From V8 to V9* : Adopt a more compact representation for message properties.
* *From V9 to V10* : Handles Mailbox ACL transactionality with event-sourcing. We got read of SERIAL consistency upon
reads thus unlocking a major performance enhancement.

The xref:distributed/operate/guide.adoc#_updating_cassandra_schema_version[Operator guide] further details the migration process.