====================
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.

For more information about the available command line arguments see :doc:`cli`.

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     | ...     | 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     | ...     | 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          |
    | information_schema | schemata          |
    | sys                | shards            |
    | information_schema | table_constraints |
    | information_schema | table_partitions  |
    | information_schema | tables            |
    +--------------------+-------------------+
    SELECT 13 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/
