CLI tools

CrateDB ships with command-line interface (CLI) tools (also referred to as executables) in the bin directory.

If your working directory is CRATE_HOME, you can run an executable like this:

sh$ bin/crate

Otherwise, you can run:

sh$ <PATH_TO_CRATE_HOME>/bin/crate

Here, replace <PATH_TO_CRATE_HOME> with a path to CRATE_HOME.

Alternatively, if the CrateDB bin directory is on your PATH, you can run an executable directly:

sh$ crate

crate

The crate executable runs the CrateDB daemon.

See also

This section is a low-level command reference. For help installing CrateDB for the first time, check out the CrateDB installation tutorial. Alternatively, consult the deployment guide for help running CrateDB in production.

Synopsis

sh$ bin/crate [-dhvCDX] [-p <PID_FILE>]

Options

Option	Description
-h	Print usage information
-v	Print version information
-C	Set a CrateDB configuration value (overrides configuration file)
-D	Set a Java system property value
-X	Set a nonstandard java option

Signal handling

The CrateDB process can handle the following signals.

Signal	Description
TERM	Terminates the process
INT	Terminates the process

Tip

The TERM signal stops CrateDB immediately. As a result, pending requests may fail. To ensure that CrateDB finishes handling pending requests before the node is stopped, you can, instead, perform a graceful stop with the DECOMMISSION statement.

Example

The simplest way to start a CrateDB instance is to invoke crate without parameters:

sh$ bin/crate

This command starts the process in the foreground.

It’s helpful to write the process ID (PID) to a PID file with the use of echo $!. So you execute the following:

sh$ bin/crate & echo $! > "/tmp/crate.pid"

To stop the process, send a TERM signal using the PID file, like so:

sh$ kill -TERM `cat /tmp/crate.pid`

crate-node

The crate-node executable is a tool that can help you:

• Repurpose a node

• Perform an unsafe cluster bootstrap

• Detach a node from its cluster

See also

This section is a low-level command reference. For help using crate-node, consult the troubleshooting guide.

Synopsis

sh$ bin/crate-node repurpose|unsafe-bootstrap|detach-cluster
[--ordinal <INT>] [-C<key>=<value>]
[-h, --help] ([-s, --silent] | [-v, --verbose])

Commands

Command	Description
repurpose	Clean up any unnecessary data on disk after changing the role of a node.
unsafe-bootstrap	Force the election of a master and create a new cluster in the event of losing the majority of master-eligible nodes.
detach-cluster	Detach a node from a cluster so that it can join a new one.
remove-settings	Remove persistent settings from the cluster state in case where it contains incompatible settings that prevent the cluster from forming.
override-version	Override the version number stored in the data path to be able to force a node to startup even when the node version is not compatible with the meta data.
fix-metadata	Fix corrupted metadata after running table swap like: ALTER CLUSTER SWAP TABLE “schema”.”table” TO “schema.table”;
remove-corrupted-data	Remove corrupted parts of a shard which cannot be automatically recovered from a good copy (replica) or restored from a backup.

Options

Option	Description
--ordinal <INT>	Specify which node to target if there is more than one node sharing a data path
-C	Set a CrateDB configuration value (overrides configuration file)
-h, --help	Return all of the command parameters
-s, --silent	Show minimal output
-v, --verbose	Shows verbose output

remove-corrupted-data

In some exceptionally cases, a CrateDB shard can become corrupted and the related table isn’t accessible. The remove-corrupted-data command helps to remove corrupted parts of a shard which cannot be automatically recovered from a good copy (replica) or restored from a backup.

Warning

You will lose data if you use the remove-corrupted-data command. Use it only as a last resort when you have no other options to recover the data.

When CratedB detects that a shard’s data is corrupted, it fails that shard copy and refuses to use it. Under normal conditions, the shard is automatically recovered from another copy. If no good copy of the shard is available and you cannot restore one from a snapshot, you can use remove-corrupted-data to remove the corrupted data and restore access to any remaining data in unaffected segments.

Warning

Stop the CrateDB node before using the remove-corrupted-data command.

There are two ways to specify the shard that you want to fix:

• With the --table option, you can specify the fully qualified name of the table that contains the shard. If you want to fix a shard of a partitioned table, you must also specify the partition values with the -P option. If the table is partitioned by multiple columns, repeat the -P option for each partition column/value pair. Additionally, the shard ID using to target a specific shard copy must be specified using the --shard-id option.

• With the --dir option, you can specify the path to the table data on disk. The path must be the one that contains the shard data, for example /data/crate/data/0/nodes/0/indices/yxZabc/0.

Options

Additional options for the remove-corrupted-data command are as follows.

Option	Description
--table <fqn_table_name>	Specifies the full-qualified table name incl. the schema name.
-P<parted_col>=<value>	Specifies the partition by partition columns. Must be repeated for every partition column. Optional, only needed for partitioned tables.
--shard-id <INT>	Specifies shard ID.
--dir <shard_path>	Specifies the path on disk of the shard to fix.
--truncate-clean-translog	If set, truncate the shard’s translog, even if not corrupted.