Skip to main content

The Crate Shell

Project description

Crate.IO Test Version Downloads


This is the Crate shell called crash.


Installing via pip

To install crash via pip use the following command:

$ pip install crash

To update use:

$ pip install -U crash

If you are using python 2.6 and pip >= 1.5 you have to pass the allow-external argument:

$ pip install crash --allow-external argparse


There is also a single file executable that includes all dependencies and can be run as long as python (>= 2.6) is available on the system.

Download Crash bundle

The bundle can then be executed using python:

python ./crash_standalone_latest


chmod +x ./crash_standalone_latest


If the package was installed using pip the shell can be started by running the command crash in a terminal.

For usage information and command line options invoke:

crash --help

Where to go from here?

to take a look at the documentation visit

Are you a Developer?

You can build Crash on your own with the latest version hosted on GitHub. To do so, please refer to DEVELOP.rst for further information.

Help & Contact

Do you have any questions? Or suggestions? We would be very happy to help you. So, feel free to swing by our IRC channel #crate on Freenode. Or for further information and official contact please visit


Copyright 2013-2014 CRATE Technology GmbH (“Crate”)

Licensed to CRATE Technology GmbH (“Crate”) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. Crate 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

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.

However, if you have executed another commercial license agreement with Crate these terms will supersede the license and you may use the software solely pursuant to the terms of the relevant commercial agreement.

Installation & Usage

If the package was installed using pip the shell can be started by invoking crash in a terminal.

pip install crash

crash by default will try to connect to localhost:4200. To connect to another host use the connect command inside the shell or use the --hosts argument when launching the shell.

crash started with the -v switch (once or more times) will log useful information when it comes to debugging, like what connection attempts are made and full tracebacks of server errors.

When you connect to a server that is not reachable or whose hostname cannot be resolved you will get an error:

cr> \connect
| server_url             | node_name | version | connected | message       |
| |      NULL | 0.0.0   | FALSE     | Server not... |
cr> \connect
| server_url           | node_name | version | connected | message         |
| |      NULL | 0.0.0   | FALSE     | Server not a... |

Successful connects will give you some information about the servers you connect to:

cr> \connect
| server_url             | node_name | version | connected | message |
| | crate     | ...     | TRUE      | OK      |

If you connect to more than one server, the command will succeed if at least one server is reachable:

cr> \connect
| server_url             | node_name | version | connected | message       |
| | crate     | ...     | TRUE      | OK            |
|   | NULL      | 0.0.0   | FALSE     | Server not... |

Once the shell is connected, SQL statements can be executed simply by entering them without any special arguments like this:

cr> SELECT schema_name, table_name FROM information_schema.tables
... ORDER BY table_name;
| schema_name        | table_name        |
| sys                | cluster           |
| information_schema | columns           |
| sys                | jobs              |
| sys                | jobs_log          |
| sys                | nodes             |
| sys                | operations        |
| sys                | operations_log    |
| information_schema | routines          |
| information_schema | schemata          |
| sys                | shards            |
| information_schema | table_constraints |
| information_schema | table_partitions  |
| information_schema | tables            |
SELECT 13 rows in set (... sec)

When the Crate shell is started with the option -v debugging information will be printed:

cr> select x from y;
SQLActionException[Table 'y' unknown]
io.crate.exceptions.TableUnknownException: Table 'y' unknown
    at io.crate.metadata.ReferenceInfos.getTableInfoUnsafe(


Nested Objects and Arrays


Since crate 0.39.0 it is possible to use object and array literals and the limitation does not apply when connecting to a crate instance running > 0.39.0.

While it is possible to select or filter by nested objects it is currently not possible to insert them using crash. In order to do that the Crate REST endpoint or a client library like crate-python has to be used.

The same also applies for arrays.

Command Line Arguments

The crash binary supports several command line arguments.

Argument Description
-h, --help Show the help message end exit.
-v, --verbose Print debug information to stdout.
-c COMMAND, --command COMMAND Execute the SQL statement and exit.
--hosts HOSTS The Crate hosts to connect to.
--history HISTORY The history file the Crate shell uses.
--format FORMAT Specifies the output format of the SQL response.

Example Usage

$ crash --hosts \
        --format json \
        -c 'select * from sys.nodes' > output.json

Crash Commands


Crash client commands are only available since version 0.11.x!

Crash has several client command, which start with a backslash (\).

You can get a list of commands by typing the command \?:

Command Description
\? List all available commands.
\c, \connect Connect to the given server. Same as --host command line option.
\dt Print existing tables. The list does not include tables in the sys and information_schema schema.
\format Switch the output format of the SQL response. Same as --format command line option. Available formats are: tabular, raw, json, csv and mixed
\q Quit Crate shell

Status Messages

The SUCCESS status messages are only printed when crash is used as an interactive tty.

If the output is routed, e.g. dumped into a file or piped into another command (such as jq) for further processing of the response, these messages are omitted.

The synopsis of the SUCCESS message is as follows:

SUCCESS <STMT>, <NUM> row(s) affected (<DURATION> sec)

If the SQL statement (SELECT) returns selected columns:

SUCCESS <STMT> <NUM> row(s) in set (<DURATION> sec)

The STMT is the definition/manipulation/query keyword, such as CREATE, INSERT, UPDATE, DELETE, SELECT, etc.

NUM is the number of rows that were affected by the SQL statement. It is -1 for statements that do not affect any rows or if the row count of a statement is unknown.


Due to Crate’s implementation, the DELETE statement always returns -1 (unknown). The reason is that Lucene does not return a count when deleting the underlying documents.

DURATION is the time it took to process the SQL statement from request to response.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
crash-0.11.4-py2.py3-none-any.whl (30.7 kB) Copy SHA256 hash SHA256 Wheel 2.7
crash-0.11.4.tar.gz (26.7 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page