Upgrade Your Cluster to 0.55.x

Claus Matzinger
Filed under
July 22, 2016

Version 0.55 of Crate introduces a lot of great features, fixes and changes.
Some of these required making changes to our code base that require extra steps
to upgrade your clusters than with previous Crate versions.

Note: Upgrading to 0.55 is only supported from Crate 0.52 and upwards.


Before upgrading a cluster it’s strongly advised to create a
of your current
tables so you can always return to what you had before. Furthermore be prepared
to restart your entire cluster.

Index Changes

Because of the Elasticsearch version upgrade, indices are not backwards
compatible to 0.54. Be aware that once upgraded to 0.55, using the same index
files in a 0.54 cluster will yield an error:

[2016-07-22 11:58:12,931][ERROR][gateway.local.state.shards] [Brian Braddock]
failed to read local state (started shards), exiting...
org.elasticsearch.ElasticsearchException: unexpected field in shard state

After upgrading your Crate version, indices will be rebuilt, and this process may take some time.

Settings Changes

There have been several changes and deprecations to the following settings
in 0.55, some due to the underlying upgrade to Elasticsearch, and others
made for reliability.

Configuration File and Location

You can no longer specify the name or location of the Crate configuration file
with the CONF_FILE environment variable, -Des.config, -Des.default.config,
or -Delasticsearch.config parameters. You must call it crate.yml and locate
it in the config directory, or another directory specified by the CONF_DIR
environmental variable, or by the -Des.path.home parameter. The file must be a
yaml file that ends in the .yml extension.

Units Required

You must now define units for time or byte based settings. This affects
Settings such as cluster.routing.allocation.disk.watermark.low for defining
the lower disk threshold limit

for shard allocations, or cluster.graceful*stop.timeout for defining the
maximum wait in milliseconds for reallocation processes to
. Please update your
configuration accordingly.

For example:

cluster.graceful_stop.timeout: 1h
# Not…
cluster.graceful_stop.timeout: 1
cluster.routing.allocation.disk.watermark.low: 250mb
# Not…
cluster.routing.allocation.disk.watermark.low: 250

Translog Syncing

The gateway.local.sync setting for controlling the period after which the
translog is synced to disk has been renamed to translog.sync_interval.

Bulk Operations

The bulk.partition_creation_timeout setting has been removed.

Automatic Job Termination

The jobs.keep_alive_timeout setting has been removed, meaning that you are no
longer able to enable automatic job termination based on defined rules.

Other Changes

Crate Does Not Start on Plugin Errors

If one of your plugins does not load properly, Crate will now refuse to start.
To remedy this, please remove any broken plugins from the plugins

Disallowing “.” Character in Field Names

Tables with column names that contain a dot are now disallowed. Consider
re-creating the table and migrating the data via insert by

2016-07-22 11:25:15,651][ERROR][gateway] [Solo] failed to read local state,
java.lang.IllegalStateException: unable to upgrade the mappings for the index
[stocks], reason: [Field name [adj. close] cannot contain '.']

Get Help

For any questions you have on upgrading your (production) cluster, join our
Slack channel
, ask on
Stackoverflow, or on

Your CrateDB download should begin automatically.

If your download did not start, click here to retry. CrateDB is also available for other platforms.

Next Steps

Stay up to date

Crate.io is constantly adding fantastic new features and making CrateDB an even better solution for you. Sign up for our newsletter to stay up to date.