You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by ad...@apache.org on 2017/07/27 06:53:54 UTC
[7/9] james-project git commit: JAMES-2096 Documentation of Cassandra
migration process
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 <bt...@linagora.com>
Authored: Wed Jul 26 09:07:42 2017 +0700
Committer: benwa <bt...@linagora.com>
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: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org