Environment Variables

CrateDB can be configured with some environment variables.

There are many different ways to set environment variables, depending on how CrateDB is being deployed.

Here is a trivial example:

sh$ export CRATE_HOME=/tmp/crate
sh$ ./bin/crate

Here, we set CRATE_HOME to /tmp/crate, export it so that sub-processes of the shell have access, and then start CrateDB.

CrateDB supports two kinds of environment variables:

• Application variables
• Java Virtual Machine (JVM) variables

We use “application” here to distinguish between CrateDB running as a Java application and the JVM itself, which runs CrateDB.

Table of Contents

• Application Variables
• JVM Variables
  • General
  • Garbage Collection
    • Collector
    • Logging

Application Variables

CRATE_HOME: directory path

The home directory of the CrateDB installation.

This directory is used as the root for the configuration directory, data directory, log directory, and so on.

If you have installed CrateDB from a package, this variable should be set for you.

If you are installing manually, in most cases, this should be set to the directory from which you would normally execute bin/crate, i.e. the root directory of the expanded tarball.

JVM Variables

General

CRATE_JAVA_OPTS: Java options

The Java options to use when running CrateDB.

For example, you could change the stack size like this:

CRATE_JAVA_OPTS=-Xss500k

See also

For more information about Java options, consult the documentation for Microsoft Windows or Unix-like operating systems.

CRATE_HEAP_SIZE: size

The Java heap size, i.e. the amount of memory that can be used.

You can set the heap size to four gigabytes like this:

CRATE_HEAP_SIZE=4g

Use g for gigabytes or m for megabytes.

See also

Appropriate memory configuration is important for optimal performance.

CRATE_HEAP_DUMP_PATH: file or directory path (default: varies)

The directory to be used for heap dumps in the case of a crash.

If a directory path is configured, new heap dumps will be written to that directory every time CrateDB crashes.

If a file path is configured (i.e. the last node of the path is non-existent or exists and is a file) CrateDB will overwrite that file with a heap dump every time it crashes.

Default values are as follows:

• For basic installations, the process working directory
• If you have installed a CrateDB Linux package, /var/lib/crate
• When running CrateDB on Docker, /data/data

Warning

Make sure there is enough disk space available for heap dumps.

Garbage Collection

Collector

CrateDB uses the Concurrent Mark Sweep garbage collector by default. When running CrateBD with a JVM >= 10, using the G1 garbage collector may result in better latency.

Example of using CRATE_JAVA_OPTS to enable the G1:

export CRATE_JAVA_OPTS="-XX:-UseConcMarkSweepGC -XX:-UseCMSInitiatingOccupancyOnly -XX:+UseG1GC -XX:InitiatingHeapOccupancyPercent=75"

Logging

CrateDB logs JVM garbage collection times using the built-in garbage collection logging of the JVM.

See also

The logging configuration documentation has the complete list of garbage collection logging environment variables.