===========
Crate Shell
===========

The crash shell provides a CLI for the Crate Server.

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

`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 127.0.0.1:65535
    +------------------------+-----------+---------+-----------+-----------...-+
    | server_url             | node_name | version | connected | message       |
    +------------------------+-----------+---------+-----------+-----------...-+
    | http://127.0.0.1:65535 |      NULL | 0.0.0   | FALSE     | Server not... |
    +------------------------+-----------+---------+-----------+-----------...-+
    CONNECT ERROR

    cr> connect null.lol:4200
    +----------------------+-----------+---------+-----------+-------------...-+
    | server_url           | node_name | version | connected | message         |
    +----------------------+-----------+---------+-----------+-------------...-+
    | http://null.lol:4200 |      NULL | 0.0.0   | FALSE     | Server not a... |
    +----------------------+-----------+---------+-----------+-------------...-+
    CONNECT ERROR

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

    cr> connect 127.0.0.1:44209
    +------------------------+-----------+---------+-----------+---------+
    | server_url             | node_name | version | connected | message |
    +------------------------+-----------+---------+-----------+---------+
    | http://127.0.0.1:44209 | crate     | 0.41.4  | TRUE      | OK      |
    +------------------------+-----------+---------+-----------+---------+
    CONNECT OK

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

    cr> CONNECT 127.0.0.1:44209 null.lol:4295
    +------------------------+-----------+---------+-----------+-----------...-+
    | server_url             | node_name | version | connected | message       |
    +------------------------+-----------+---------+-----------+-----------...-+
    | http://127.0.0.1:44209 | crate     | 0.41.4  | TRUE      | OK            |
    | http://null.lol:4295   | NULL      | 0.0.0   | FALSE     | Server not... |
    +------------------------+-----------+---------+-----------+-----------...-+
    CONNECT OK

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          |
    | sys                | shards            |
    | information_schema | table_constraints |
    | information_schema | table_partitions  |
    | information_schema | tables            |
    +--------------------+-------------------+
    SELECT 12 rows in set (... sec)


Limitations
===========

Nested Objects and Arrays
-------------------------

.. note::

    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.

.. _`Crate REST endpoint`: https://crate.io/docs/current/sql/rest.html
.. _`crate-python`: https://pypi.python.org/pypi/crate/
