JAMES-2096 Documentation of Cassandra migration process
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/8ec5e96f Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/8ec5e96f Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/8ec5e96f Branch: refs/heads/master Commit: 8ec5e96f694409f9331439e9eea0dcf6ab6fe095 Parents: 28855e7 Author: benwa <[email protected]> Authored: Wed Jul 26 09:07:42 2017 +0700 Committer: benwa <[email protected]> Committed: Wed Jul 26 09:08:11 2017 +0700 ---------------------------------------------------------------------- src/site/markdown/server/manage-webadmin.md | 95 +++++++++++++++++++++++- src/site/xdoc/server/config-cassandra.xml | 16 ++++ 2 files changed, 110 insertions(+), 1 deletion(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/james-project/blob/8ec5e96f/src/site/markdown/server/manage-webadmin.md ---------------------------------------------------------------------- diff --git a/src/site/markdown/server/manage-webadmin.md b/src/site/markdown/server/manage-webadmin.md index 04d8d07..2f9a2f6 100644 --- a/src/site/markdown/server/manage-webadmin.md +++ b/src/site/markdown/server/manage-webadmin.md @@ -331,4 +331,97 @@ Response codes: - 204: Success - 400: Invalid JSON, or numbers are less than -1. - - 500: Internal error \ No newline at end of file + - 500: Internal error + +## Cassandra Schema upgrades + +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 webadmin using the Cassandra backend. + +Note that currently the progress can be tracked by logs. + +### Retrieving current Cassandra schema version + +``` +curl -XGET http://ip:port/cassandra/version +``` + +Will return: + +``` +2 +``` + +Where the number corresponds to the current schema version of the database you are using. + +Response codes: + + - 200: Success + - 500: Internal error + +### Retrieving latest available Cassandra schema version + +``` +curl -XGET http://ip:port/cassandra/version +``` + +Will return: + +``` +3 +``` + +Where the number corresponds to the latest available schema version of the database you are using. This means you can be +migrating to this schema version. + +Response codes: + + - 200: Success + - 500: Internal error + +### Upgrading to a specific version + +``` +curl -XPOST http://ip:port/cassandra/version/upgrade -d '3' +``` + +Will run the migrations you need to reach schema version 3. + +Response codes: + + - 204: Success + - 400: The version is invalid. The version should be a strictly positive number. + - 410: Error running the migration. This resource is gone away. Reason is mentionned in the body. + - 500: Internal error. This can result from a partial migration, in which case the reason is contained in the body. + +Note that several calls to this endpoint will be run in a sequential pattern. + +If the server restarts during the migration, the migration is silently aborted. + +### Upgrading to the latest version + +``` +curl -XPOST http://ip:port/cassandra/version/upgrade/latest +``` + +Will run the migrations you need to reach the latest schema version. + +Response codes: + + - 204: Success + - 410: Error running the migration. This resource is gone away. Reason is mentionned in the body. + - 500: Internal error. This can result from a partial migration, in which case the reason is contained in the body. + +Note that several calls to this endpoint will be run in a sequential pattern. + +If the server restarts during the migration, the migration is silently aborted. + http://git-wip-us.apache.org/repos/asf/james-project/blob/8ec5e96f/src/site/xdoc/server/config-cassandra.xml ---------------------------------------------------------------------- diff --git a/src/site/xdoc/server/config-cassandra.xml b/src/site/xdoc/server/config-cassandra.xml index cd3bb24..fab44ec 100644 --- a/src/site/xdoc/server/config-cassandra.xml +++ b/src/site/xdoc/server/config-cassandra.xml @@ -126,6 +126,22 @@ </section> + <section name="Cassandra migration process"> + <p>Cassandra upgrades implies the creation of a new table. Thus restarting James is needed, as new tables are created on restart.</p> + + <p>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.</p> + + <p>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...</p> + + <p>These schema updates can be triggered by <a href="manage-webadmin.html">webadmin</a> using the Cassandra backend.</p> + + <p>Note that currently the progress can be tracked by logs.</p> + </section> + </body> </document> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
