| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- Generated by Apache Maven Doxia at 2021-09-26 --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <title>Apache James Project – Apache James Server 3 - Cassandra Configuration</title> |
| <style type="text/css" media="all"> |
| @import url("../css/james.css"); |
| @import url("../css/maven-base.css"); |
| @import url("../css/maven-theme.css"); |
| @import url("../css/site.css"); |
| @import url("../js/jquery/css/custom-theme/jquery-ui-1.8.5.custom.css"); |
| @import url("../js/jquery/css/print.css"); |
| @import url("../js/fancybox/jquery.fancybox-1.3.4.css"); |
| </style> |
| <script type="text/javascript" src="../js/jquery/js/jquery-1.4.2.min.js"></script> |
| <script type="text/javascript" src="../js/jquery/js/jquery-ui-1.8.5.custom.min.js"></script> |
| <script type="text/javascript" src="../js/fancybox/jquery.fancybox-1.3.4.js"></script> |
| <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> |
| <meta name="Date-Revision-yyyymmdd" content="20210926" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| |
| <!-- Google Analytics --> |
| <script type="text/javascript"> |
| |
| var _gaq = _gaq || []; |
| _gaq.push(['_setAccount', 'UA-1384591-1']); |
| _gaq.push(['_trackPageview']); |
| |
| (function() { |
| var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
| ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; |
| var s = document.getElementsByTagName('script').item(0); s.parentNode.insertBefore(ga, s); |
| })(); |
| |
| </script> |
| </head> |
| <body class="composite"> |
| <div id="banner"> |
| <a href="../index.html" id="bannerLeft" title="james-logo.png"> |
| |
| |
| <img src="../images/logos/james-logo.png" alt="James Project" /> |
| </a> |
| <a href="https://www.apache.org/index.html" id="bannerRight"> |
| |
| |
| <img src="images/logos/asf_logo_small.png" alt="The Apache Software Foundation" /> |
| </a> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="breadcrumbs"> |
| |
| |
| <div class="xleft"> |
| <span id="publishDate">Last Published: 2021-09-26</span> |
| </div> |
| <div class="xright"> <a href="../index.html" title="Home">Home</a> |
| | |
| <a href="../documentation.html" title="James">James</a> |
| | |
| <a href="../mime4j/index.html" title="Mime4J">Mime4J</a> |
| | |
| <a href="../jsieve/index.html" title="jSieve">jSieve</a> |
| | |
| <a href="../jspf/index.html" title="jSPF">jSPF</a> |
| | |
| <a href="../jdkim/index.html" title="jDKIM">jDKIM</a> |
| |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="leftColumn"> |
| <div id="navcolumn"> |
| |
| |
| <h5>James components</h5> |
| <ul> |
| <li class="collapsed"> |
| <a href="../documentation.html" title="About James">About James</a> |
| </li> |
| <li class="expanded"> |
| <a href="../server/index.html" title="Server">Server</a> |
| <ul> |
| <li class="none"> |
| <a href="../server/advantages.html" title="Advantages">Advantages</a> |
| </li> |
| <li class="none"> |
| <a href="../server/objectives.html" title="Objectives">Objectives</a> |
| </li> |
| <li class="expanded"> |
| <a href="../server/quick-start.html" title="User Manual">User Manual</a> |
| <ul> |
| <li class="collapsed"> |
| <a href="../server/features.html" title="1. Features">1. Features</a> |
| </li> |
| <li class="none"> |
| <a href="../server/packaging.html" title="2. Packaging">2. Packaging</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../server/install.html" title="3. Install James">3. Install James</a> |
| </li> |
| <li class="expanded"> |
| <a href="../server/config.html" title="4. Configure James">4. Configure James</a> |
| <ul> |
| <li class="none"> |
| <a href="../server/config-listeners.html" title="Additional mailbox listeners">Additional mailbox listeners</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-antispam.html" title="Anti Spam">Anti Spam</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-blob-export.html" title="Blob Export">Blob Export</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-blobstore.html" title="BlobStore">BlobStore</a> |
| </li> |
| <li class="none"> |
| <strong>Cassandra</strong> |
| </li> |
| <li class="none"> |
| <a href="../server/config-elasticsearch.html" title="ElasticSearch">ElasticSearch</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-vault.html" title="Deleted Messages Vault">Deleted Messages Vault</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-dnsservice.html" title="DNS Service">DNS Service</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-domainlist.html" title="Domain List">Domain List</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-fetchmail.html" title="FetchMail">FetchMail</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-guice.html" title="Guice">Guice</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-imap4.html" title="IMAP4">IMAP4</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-jmap.html" title="JMAP">JMAP</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-mailrepositorystore.html" title="Mail Repository Stores">Mail Repository Stores</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-mailbox.html" title="Mailbox">Mailbox</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-mailetcontainer.html" title="Mailet Container">Mailet Container</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-healthcheck.html" title="Periodical Health Checks">Periodical Health Checks</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-pop3.html" title="POP3">POP3</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-quota.html" title="Quota">Quota</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-rabbitmq.html" title="RabbitMQ">RabbitMQ</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-recipientrewritetable.html" title="Recipient Rewrite">Recipient Rewrite</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-smtp-lmtp.html" title="SMTP LMTP">SMTP LMTP</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-sieve.html" title="Sieve">Sieve</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-ssl-tls.html" title="SSL/TLS">SSL/TLS</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-system.html" title="System">System</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-spring-jpa-postgres.html" title="Spring JPA Postgres">Spring JPA Postgres</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-users.html" title="Users">Users</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-webadmin.html" title="WebAdmin">WebAdmin</a> |
| </li> |
| </ul> |
| </li> |
| <li class="collapsed"> |
| <a href="../server/manage.html" title="5. Manage">5. Manage</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../server/monitor.html" title="6. Monitor">6. Monitor</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../server/upgrade.html" title="7. Upgrade">7. Upgrade</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../server/dev.html" title="8. Developers Corner">8. Developers Corner</a> |
| </li> |
| </ul> |
| </li> |
| <li class="none"> |
| <a href="../mail.html#James_Mailing_lists" title="Mailing Lists">Mailing Lists</a> |
| </li> |
| <li class="none"> |
| <a href="../server/release-notes.html" title="Release Notes">Release Notes</a> |
| </li> |
| <li class="none"> |
| <a href="../server/apidocs/index.html" title="Javadoc">Javadoc</a> |
| </li> |
| <li class="none"> |
| <a href="https://issues.apache.org/jira/browse/JAMES" title="Issue Tracker">Issue Tracker</a> |
| </li> |
| <li class="none"> |
| <a href="https://github.com/apache/james-project" title="Sources">Sources</a> |
| </li> |
| <li class="none"> |
| <a href="../server/rfcs.html" title="RFCs">RFCs</a> |
| </li> |
| <li class="none"> |
| <a href="../download.cgi#Apache_James_Server" title="Download releases">Download releases</a> |
| </li> |
| </ul> |
| </li> |
| <li class="collapsed"> |
| <a href="../mailet/index.html" title="Mailets">Mailets</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../mailbox/index.html" title="Mailbox">Mailbox</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../protocols/index.html" title="Protocols">Protocols</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../mpt/index.html" title="MPT">MPT</a> |
| </li> |
| </ul> |
| <h5>Apache Software Foundation</h5> |
| <ul> |
| <li> |
| <strong> |
| <a title="ASF" href="http://www.apache.org/">ASF</a> |
| </strong> |
| </li> |
| <li> |
| <a title="Get Involved" href="http://www.apache.org/foundation/getinvolved.html">Get Involved</a> |
| </li> |
| <li> |
| <a title="FAQ" href="http://www.apache.org/foundation/faq.html">FAQ</a> |
| </li> |
| <li> |
| <a title="License" href="http://www.apache.org/licenses/" >License</a> |
| </li> |
| <li> |
| <a title="Sponsorship" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| </li> |
| <li> |
| <a title="Thanks" href="http://www.apache.org/foundation/thanks.html">Thanks</a> |
| </li> |
| <li> |
| <a title="Security" href="http://www.apache.org/security/">Security</a> |
| </li> |
| </ul> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /> |
| </a> |
| |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| |
| |
| |
| |
| <section> |
| <h2><a name="Cassandra_Configuration"></a>Cassandra Configuration</h2> |
| |
| Note: Cassandra is only available with Guice wiring (cassandra-guice and cassandra-guice-ldap). |
| |
| |
| <p>Consult <a class="externalLink" href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/cassandra.properties">cassandra.properties</a> to get some examples and hints.</p> |
| |
| |
| <dl> |
| |
| <dt><b>cassandra.nodes</b></dt> |
| |
| <dd>List of some nodes of the cassandra's cluster in following format host:port or host, if the port is not specified we use 9042</dd> |
| |
| |
| <dt><b>cassandra.keyspace.create</b></dt> |
| |
| <dd>Indicate if the keyspace should be created by James. Optional, default value: <b>false</b><br /> |
| If set to true James will attempt to create the keyspace when starting up.<br /> |
| </dd> |
| |
| |
| <dt><b>cassandra.keyspace</b></dt> |
| |
| <dd>Is the name of the keyspace used by James. Optional, default value: <b>apache_james</b></dd> |
| |
| |
| <dt><b>cassandra.user</b></dt> |
| |
| <dd>Username used as a credential for contacting Cassandra cluster. Optional, default is absent, |
| required if <b>cassandra.password</b> is supplied</dd> |
| |
| |
| <dt><b>cassandra.password</b></dt> |
| |
| <dd>Password used as a credential for contacting Cassandra cluster. Optional, default is absent, |
| required if <b>cassandra.user</b> is supplied</dd> |
| |
| |
| <dt><b>cassandra.ssl</b></dt> |
| |
| <dd>Whether SSL should be enabled on the communications with Cassandra cluster. Optional, defaults to false.<br /> |
| The keystore used for trusting SSL server socket can be set via JSSE system properties as explained on |
| <a class="externalLink" href="https://docs.datastax.com/en/developer/java-driver/3.7/manual/ssl/">Cassandra driver manual</a>.</dd> |
| |
| |
| <dt><b>cassandra.replication.factor</b></dt> |
| |
| <dd>Is the replication factor used upon keyspace creation. Modifying this property while the keyspace already exists |
| will have no effect. Optional. Default value 1.</dd> |
| |
| |
| <dt><b>cassandra.query.logger.constant.threshold</b></dt> |
| |
| <dd>Optional. |
| If specified all queries that take more than the given integer in millisecond will be considered slow and logged. |
| If not specified by default a DynamicThresholdQueryLogger will be used (see above)</dd> |
| |
| |
| <dt><b>cassandra.query.slow.query.latency.threshold.percentile</b></dt> |
| |
| <dd>Default is com.datastax.driver.core.QueryLogger.DEFAULT_SLOW_QUERY_THRESHOLD_PERCENTILE. |
| The latency percentile beyond which queries are considered 'slow' and will be logged. |
| If you specify cassandra.query.logger.constant.threshold, you should not specify this property</dd> |
| |
| |
| <dt><b>cassandra.query.logger.max.query.string.length</b></dt> |
| |
| <dd>Default is com.datastax.driver.core.QueryLogger.DEFAULT_MAX_QUERY_STRING.LENGTH. |
| The maximum length of a CQL query string that can be logged verbatim by the cassandra driver</dd> |
| |
| |
| <dt><b>cassandra.query.logger.max.logged.parameters</b></dt> |
| |
| <dd>Default is com.datastax.driver.core.QueryLogger.DEFAULT_MAX_LOGGED_PARAMETERS. |
| The maximum number of query parameters that can be logged by the cassandra driver</dd> |
| |
| |
| <dt><b>cassandra.query.logger.max.parameter.value.length</b></dt> |
| |
| <dd>Default is com.datastax.driver.core.QueryLogger.DEFAULT_MAX_PARAMETER_VALUE_LENGTH. |
| The maximum length of query parameter value that can be logged by the cassandra driver</dd> |
| |
| |
| <dt><b>cassandra.readTimeoutMillis</b></dt> |
| |
| <dd>Optional. |
| If specified defines the Cassandra <a class="externalLink" href="https://docs.datastax.com/en/developer/java-driver/3.5/manual/socket_options/">driver read timeout</a>.</dd> |
| |
| |
| |
| <div> |
| <pre># Read com.datastax.driver.core.PoolingOptions for knowing defaults value |
| # No value here will default to driver's default value |
| |
| # cassandra.pooling.local.max.connections=8 |
| # cassandra.pooling.local.max.requests=128 |
| ## In ms. Should be higher than socket read timeout |
| # cassandra.pooling.timeout=5000 |
| ## In seconds. |
| # cassandra.pooling.heartbeat.timeout=30 |
| # cassandra.pooling.max.queue.size=256</pre></div> |
| |
| |
| <dt><b>cassandra.pooling.local.max.connections</b></dt> |
| |
| <dd>Optional. Defaults to 8.<br /> |
| If specified defines the Cassandra <a class="externalLink" href="https://docs.datastax.com/en/developer/java-driver/3.5/manual/pooling/#pool-size">maximum number of connections to hosts</a> (remote and local).</dd> |
| |
| |
| <dt><b>cassandra.pooling.local.max.requests</b></dt> |
| |
| <dd>Optional. Defaults to 128.<br /> |
| If specified defines the Cassandra <a class="externalLink" href="https://docs.datastax.com/en/developer/java-driver/3.5/manual/pooling/">maximum number of concurrent requests per connection</a>.</dd> |
| |
| |
| <dt><b>cassandra.pooling.timeout</b></dt> |
| |
| <dd>Optional. Defaults to 5000 (ms).<br /> |
| If specified defines the Cassandra <a class="externalLink" href="https://docs.datastax.com/en/developer/java-driver/3.5/manual/pooling/#acquisition-queue">timeout for waiting in the pool queue</a>. Should be higher than sockets timeout.</dd> |
| |
| |
| <dt><b>cassandra.pooling.heartbeat.timeout</b></dt> |
| |
| <dd>Optional. Defaults to 30 (s).<br /> |
| If specified defines the Cassandra <a class="externalLink" href="https://docs.datastax.com/en/developer/java-driver/3.5/manual/pooling/#heartbeat">heartbeat timeout</a>.</dd> |
| |
| |
| <dt><b>cassandra.pooling.max.queue.size</b></dt> |
| |
| <dd>Optional. Defaults to 256.<br /> |
| If specified defines the Cassandra <a class="externalLink" href="https://docs.datastax.com/en/developer/java-driver/3.5/manual/pooling/#acquisition-queue">maximum size of the connection pool queue</a>.</dd> |
| |
| |
| <dt><b>mailbox.read.repair.chance</b></dt> |
| |
| <dd>Optional. Defaults to 0.1 (10% chance).<br /> Must be between 0 and 1 (inclusive). Controls the probability of doing a read-repair upon mailbox read.</dd> |
| |
| <dt><b>mailbox.counters.read.repair.chance.max</b></dt> |
| |
| <dd>Optional. Defaults to 0.1 (10% chance).<br /> |
| Must be between 0 and 1 (inclusive). Controls the probability of doing a read-repair upon mailbox counters read.<br /> |
| Formula: read_repair_chance = min(mailbox.counters.read.repair.chance.max, (100/unseens)*mailbox.counters.read.repair.chance.one.hundred) |
| </dd> |
| |
| <dt><b>mailbox.counters.read.repair.chance.one.hundred</b></dt> |
| |
| <dd>Optional. Defaults to 0.01 (1% chance).<br /> |
| Must be between 0 and 1 (inclusive). Controls the probability of doing a read-repair upon mailbox counters read.<br /> |
| Formula: read_repair_chance = min(mailbox.counters.read.repair.chance.max, (100/unseens)*mailbox.counters.read.repair.chance.one.hundred) |
| </dd> |
| |
| <dt><b>mailbox.max.retry.acl</b></dt> |
| |
| <dd>Optional. Defaults to 1000.<br /> Controls the number of retries upon Cassandra ACL updates.</dd> |
| |
| <dt><b>mailbox.max.retry.modseq</b></dt> |
| |
| <dd>Optional. Defaults to 100000.<br /> Controls the number of retries upon Cassandra ModSeq generation.</dd> |
| |
| <dt><b>mailbox.max.retry.uid</b></dt> |
| |
| <dd>Optional. Defaults to 100000.<br /> Controls the number of retries upon Cassandra Uid generation.</dd> |
| |
| <dt><b>mailbox.max.retry.message.flags.update</b></dt> |
| |
| <dd>Optional. Defaults to 1000.<br /> Controls the number of retries upon Cassandra flags update, in MessageMapper.</dd> |
| |
| <dt><b>mailbox.max.retry.message.id.flags.update</b></dt> |
| |
| <dd>Optional. Defaults to 1000.<br /> Controls the number of retries upon Cassandra flags update, in MessageIdMapper.</dd> |
| |
| <dt><b>fetch.advance.row.count</b></dt> |
| |
| <dd>Optional. Defaults to 1000.<br /> Controls the number of remaining rows we should wait before prefetch when paging.</dd> |
| |
| <dt><b>chunk.size.message.read</b></dt> |
| |
| <dd>Optional. Defaults to 100.<br /> Controls the number of messages to be retrieved in parallel.</dd> |
| |
| <dt><b>chunk.size.expunge</b></dt> |
| |
| <dd>Optional. Defaults to 50.<br /> Controls the number of messages to be expunged in parallel.</dd> |
| |
| <dt><b>mailbox.blob.part.size</b></dt> |
| |
| <dd>Optional. Defaults to 102400 (100KB).<br /> Controls the size of blob parts used to store messages.</dd> |
| |
| |
| <dt><b>mailbox.read.strong.consistency</b></dt> |
| |
| <dd>Optional. Boolean, defaults to true. Disabling should be considered experimental. |
| If enabled, regular consistency level is used for read transactions for mailbox. Not doing so might result |
| in stale reads as the system.paxos table will not be checked for latest updates. Better performance are expected |
| by turning it off. Note that reads performed as part of write transactions are always performed with a strong |
| consistency.</dd> |
| |
| |
| <dt><b>message.read.strong.consistency</b></dt> |
| |
| <dd>Optional. Boolean, defaults to true. Disabling should be considered experimental. |
| If enabled, regular consistency level is used for read transactions for message. Not doing so might result |
| in stale reads as the system.paxos table will not be checked for latest updates. Better performance are expected |
| by turning it off. Note that reads performed as part of write transactions are always performed with a strong |
| consistency.</dd> |
| |
| |
| <dt><b>message.write.strong.consistency.unsafe</b></dt> |
| |
| <dd>Optional. Boolean, defaults to true. Disabling should be considered experimental and unsafe. |
| If disabled, Lightweight transactions will no longer be used upon messages operation (table `imapUidTable`). |
| As message flags updates relies so far on a read-before-write model, it exposes yourself to data races leading to |
| potentially update loss. Better performance are expected |
| by turning it off. Reads performed as part of write transaction are also performed with a relaxed consistency.</dd> |
| |
| |
| <dt><b>Allows specifying the driver default consistency level.</b></dt> |
| |
| <dt><b>cassandra.consistency_level.regular</b></dt> |
| |
| <dd>Optional. Defaults to QUORUM.<br /> <a class="externalLink" href="https://docs.datastax.com/en/cassandra-oss/3.x/cassandra/dml/dmlConfigConsistency.html">QUORUM, LOCAL_QUORUM, or EACH_QUORUM</a>.</dd> |
| |
| <dt><b>cassandra.consistency_level.lightweight_transaction</b></dt> |
| |
| <dd>Optional. Defaults to SERIAL.<br /> <a class="externalLink" href="https://docs.datastax.com/en/cassandra-oss/3.x/cassandra/dml/dmlConfigConsistency.html">SERIAL or LOCAL_SERIAL</a>.</dd> |
| |
| <dt><b>cassandra.local.dc</b></dt> |
| |
| <dd>Optional. Allows specifying the local DC as part of the load balancing policy. Specifying it |
| would result in the use of new TokenAwarePolicy(DCAwareRoundRobinPolicy.builder().withLocalDc(value).build()) as a LoadBalancingPolicy. |
| This value is useful in a multi-DC Cassandra setup. Be aware of limitations of multi-DC setups for James. |
| Not specifying this value results in the driver's default load balancing policy to be used.</dd> |
| |
| <dt><b>optimistic.consistency.level.enabled</b></dt> |
| |
| <dd>Optional. Defaults to false. Allows specifying consistency level ONE for reads in Cassandra BlobStore. |
| Falls back to default read consistency level if the blob is missing.</dd> |
| </dl> |
| |
| |
| |
| <p>If you want more explanation about Cassandra configuration, you should visit the dedicated <a class="externalLink" href="http://docs.datastax.com/en/cassandra/2.1/cassandra/gettingStartedCassandraIntro.html">documentation</a>.</p> |
| |
| </section> |
| |
| <section> |
| <h2><a name="Cassandra_migration_process"></a>Cassandra migration process</h2> |
| |
| <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> |
| |
| Here are the implemented migrations: |
| |
| <section> |
| <h3><a name="From_V1_to_V2"></a>From V1 to V2</h3> |
| |
| |
| <p>Last support on releases 3.5.0</p> |
| |
| |
| <p>Migration tag on git repository: <a class="externalLink" href="https://github.com/apache/james-project/releases/tag/cassandra_migration_v1_to_v2">cassandra_migration_v1_to_v2</a></p> |
| |
| |
| <p>Goal is to create a messageV2 table that aims at replacing message table. Message table is both storing message |
| metadata and blobs. It have been proven inefficient. Instead version 2 is chunking message blobs and storing it |
| in an other table. The migration process involves moving all messages from message table to messageV2 table |
| (contains only metadata) and blobs / blobParts tables.</p> |
| |
| |
| <p>Read more about this migration <a class="externalLink" href="https://medium.com/p/7e8607eb3c4f">here</a>.</p> |
| |
| |
| <p>Summary of available options for this migration:</p> |
| |
| |
| <dl> |
| |
| <dt><b>migration.v1.v2.on.the.fly</b></dt> |
| |
| <dd>Only available on tag cassandra_migration_v1_to_v2. Optional. Defaults to false.<br /> Controls wether v1 to v2 migration should be run on the fly.</dd> |
| |
| <dt><b>migration.v1.v2.thread.count</b></dt> |
| |
| <dd>Only available on tag cassandra_migration_v1_to_v2. Optional. Defaults to 2.<br /> Controls the number of threads used to asynchronously migrate from v1 to v2.</dd> |
| |
| <dt><b>migration.v1.v2.queue.length</b></dt> |
| |
| <dd>Only available on tag cassandra_migration_v1_to_v2. Optional. Defaults to 1000.<br /> Controls the queue size of v1 to v2 migration task. Drops when full.</dd> |
| |
| <dt><b>migration.v1.read.fetch.size</b></dt> |
| |
| <dd>Only available on tag cassandra_migration_v1_to_v2. Optional. Defaults to 10.<br /> Controls the fetch size of the request to retrieve all messages stored in V1 during the migration process.</dd> |
| </dl> |
| |
| </section> |
| |
| <section> |
| <h3><a name="From_V2_to_V3"></a>From V2 to V3</h3> |
| |
| |
| <p>Last support on releases 3.5.0</p> |
| |
| |
| <p>Migration tag on git repository: <a class="externalLink" href="https://github.com/apache/james-project/releases/tag/cassandra_migration_v2_to_v3">cassandra_migration_v2_to_v3</a></p> |
| |
| |
| <p>Goal is to drop <b>message</b> table. After this migration, one can manually delete this table.</p> |
| |
| </section> |
| |
| <section> |
| <h3><a name="From_V3_to_V4"></a>From V3 to V4</h3> |
| |
| |
| <p>Last support on releases 3.5.0</p> |
| |
| |
| <p>Migration tag on git repository: <a class="externalLink" href="https://github.com/apache/james-project/releases/tag/cassandra_migration_v3_to_v4">cassandra_migration_v3_to_v4</a></p> |
| |
| |
| <p>Goal is to store attachments in the blob tables.</p> |
| |
| |
| <p>Summary of available options for this migration:</p> |
| |
| |
| <dl> |
| |
| <dt><b>attachment.v2.migration.read.timeout</b></dt> |
| |
| <dd>Optional. Defaults to one day.<br /> Controls how many milliseconds before the read on attachment v1 time out.</dd> |
| </dl> |
| |
| </section> |
| |
| <section> |
| <h3><a name="From_V4_to_V5"></a>From V4 to V5</h3> |
| |
| |
| <p>Last support on releases 3.5.0</p> |
| |
| |
| <p>Migration tag on git repository: <a class="externalLink" href="https://github.com/apache/james-project/releases/tag/cassandra_migration_v4_to_v5">cassandra_migration_v4_to_v5</a></p> |
| |
| |
| <p>Goal is to store attachment ids in the separated AttachmentMessageId table.</p> |
| |
| |
| <p>Summary of available options for this migration:</p> |
| |
| |
| <dl> |
| |
| <dt><b>message.attachmentids.read.timeout</b></dt> |
| |
| <dd>Optional. Defaults to one day.<br /> Controls how many milliseconds before the read attachment ids on message time out.</dd> |
| </dl> |
| |
| </section> |
| |
| <section> |
| <h3><a name="From_V5_to_V6"></a>From V5 to V6</h3> |
| |
| |
| <p>Last support on releases 3.6.x</p> |
| |
| |
| <p>Goal is to no longer rely on an UDT partition key for mailboxPath tables. Entries will be migrated to mailboxPathV2 table relying on a composite primary key</p> |
| |
| </section> |
| |
| <section> |
| <h3><a name="From_V6_to_V7"></a>From V6 to V7</h3> |
| |
| |
| <p>Last support on releases 3.6.x</p> |
| |
| |
| <p>Goal is to populate mapping_sources projection table. This table allows finding the source of a given redirection, which is |
| handy for things like mail aliases (I want to list aliases rewritting things to bob). Without this projection table being available, |
| (ie we rely on schema version 6 or less) such information is obtained through a full table scan, unoptimized. From schema version 7, |
| the optimized projection can safely be used.</p> |
| |
| </section> |
| |
| <section> |
| <h3><a name="From_V7_to_V8"></a>From V7 to V8</h3> |
| |
| |
| <p>Last support on releases 3.6.x</p> |
| |
| |
| <p>Add UID_VALIDITY to mailboxPath table in order not to mandate mailbox table reads.</p> |
| |
| </section> |
| |
| <section> |
| <h3><a name="From_V8_to_V9"></a>From V8 to V9</h3> |
| |
| |
| <p>Adopt a more compact representation for message properties.</p> |
| |
| </section> |
| |
| <section> |
| <h3><a name="From_V9_to_V10"></a>From V9 to V10</h3> |
| |
| |
| <p>Handles Mailbox ACL transactionality with event-sourcing. We got read of SERIAL consistency upon reads thus unlocking a |
| major performance enhancement.</p> |
| |
| </section> |
| |
| <section> |
| <h3><a name="Adding_threadId_column_to_message_metadata_tables"></a>Adding threadId column to message metadata tables</h3> |
| |
| |
| <p>Add threadId column to messageIdTable and imapUidTable in order to get a message's threadId.</p> |
| |
| </section> |
| |
| </section> |
| |
| |
| |
| |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright">Copyright © 2006-2021 |
| <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| All Rights Reserved. |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| </body> |
| </html> |
