Skip to content

Commit

Permalink
complete docs rewrite
Browse files Browse the repository at this point in the history
  • Loading branch information
Naomi Slater committed Apr 21, 2018
1 parent 65afd79 commit dbfcb05
Show file tree
Hide file tree
Showing 11 changed files with 448 additions and 169 deletions.
67 changes: 40 additions & 27 deletions README.rst
View file
@@ -1,50 +1,60 @@
=====
Crash
=====
=================
The CrateDB Shell
=================

.. image:: https://travis-ci.org/crate/crash.svg?branch=master
:target: https://travis-ci.org/crate/crash
:alt: Travis CI

.. image:: https://badge.fury.io/py/crash.png
.. image:: https://badge.fury.io/py/crash.svg
:target: http://badge.fury.io/py/crash
:alt: Version

.. image:: https://img.shields.io/badge/docs-latest-brightgreen.svg
:target: https://crate.io/docs/reference/crash/
:alt: Documentation

.. image:: https://img.shields.io/pypi/pyversions/crash.svg
:target: https://pypi.python.org/pypi/crash/
:alt: Python Version

.. image:: https://img.shields.io/coveralls/crate/crash.svg
:target: https://coveralls.io/r/crate/crash?branch=master
.. image:: https://coveralls.io/repos/github/crate/crash/badge.svg?branch=master
:target: https://coveralls.io/github/crate/crash?branch=master
:alt: Coverage

|
Crash is an interactive CrateDB *command line interface* (CLI) SQL shell with autocompletion.

The CrashDB Shell (aka *Crash*) is an interactive `command-line interface`_
(CLI) tool for interacting with CrateDB.

Screenshot
==========

.. image:: crash.png
.. image:: docs/query.png
:alt: A screenshot of Crash

Prerequisites
=============

Recent versions of Crash require **Python 3** (>= 3.4) to run.
Recent versions of Crash require Python 3 (>= 3.4) to run.

Use Crash version 0.23.x if you are running Python 2.7 or 3.3.

Use Crash version ``0.23.x`` if you are running Python 2.7/3.3 or version
``0.16.x`` if you're running Python 2.6.
Use Crash version 0.16.x if you're running Python 2.6.

Installation
============

As a Python Package
-------------------
Under normal circumstances, you do not have to manually install Crash.

Crash is bundled with CrateDB so there is typically no need to install it
yourself.

If you are able to run the ``crate`` command, you should be able to run the
``crash`` command (either from the same ``bin`` directory, or on your `PATH`_).

The following instructions should only be followed if you specifically want to
install Crash separately from CrateDB.

Python Package
--------------

Crash is available as a pip_ package.

Expand All @@ -60,39 +70,40 @@ To update, run::

$ pip install -U crash

If you use Python 2.7 or 3.3 with a recent version of pip_, it will install
only version ``0.23.x`` by default, because newer versions of this package are
not compatible with Python 2.7/3.3 any more.
If you are not using Python version 3.4 or above, recent version of pip_ will
only install version 0.23.x. This is because newer versions of this package are
not compatible with Python 2.7 or 3.3 and below.

Standalone
----------

Crash is also available as a standalone executable that includes all the
necessary dependencies, and can be run as long as Python (>= 3.4) is available.
necessary dependencies, and can be run as long as Python (>= 3.4) is available
on your system.

First, download the executable::
First, download the executable file::

$ curl -o crash https://cdn.crate.io/downloads/releases/crash_standalone_latest

Then, make it executable::
Then, set the executable bit::

$ chmod +x crash

Now, run it::

$ ./crash

If you would like to run ``crash`` from any directory and without using leading
``./`` you will need to move it to somewhere on your ``$PATH``.
If you would like to run ``crash`` from any directory, and without the leading
``./``, the file has to be in a directory that is on your `PATH`_.

Legacy Versions
...............

For Python 2.7 and 3.3 please download version ``0.23.0`` from the CDN::
For Python 2.7 and 3.3 please download version 0.23.0 from the CDN::

$ curl -o crash https://cdn.crate.io/downloads/releases/crash_standalone_0.23.0

For Python 2.6 please download version ``0.16.2`` from the CDN::
For Python 2.6 please download version 0.16.2 from the CDN::

$ curl -o crash https://cdn.crate.io/downloads/releases/crash_standalone_0.16.2

Expand Down Expand Up @@ -121,10 +132,12 @@ Looking for more help?
- Chat with us on `Slack`_
- Get `paid support`_

.. _command-line interface: https://en.wikipedia.org/wiki/Command-line_interface
.. _contribution docs: CONTRIBUTING.rst
.. _Crate.io: http://crate.io/
.. _developer docs: DEVELOP.rst
.. _paid support: https://crate.io/pricing/
.. _PATH: https://en.wikipedia.org/wiki/PATH_(variable)
.. _pip: https://pypi.python.org/pypi/pip
.. _Slack: https://crate.io/docs/support/slackin/
.. _StackOverflow: https://stackoverflow.com/tags/crate
Expand Down
Binary file added docs/autocomplete.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
66 changes: 66 additions & 0 deletions docs/commands.txt
View file
@@ -0,0 +1,66 @@
.. _commands:

========
Commands
========

Crash has several built-in client commands that you can run from the prompt.

Every command starts with a ``\`` character.

+------------------------+-----------------------------------------------------+
| Command | Description |
+========================+=====================================================+
| ``\?`` | List all available commands. |
+------------------------+-----------------------------------------------------+
| | ``\c <HOSTS>``, | Connect to ``<HOSTS>``. |
| | ``\connect <HOSTS>`` | |
| | |
| | Same as ``--hosts`` command line option. |
| | |
| | ``HOSTS`` can be a single host, or it can be a |
| | space separated list of hosts. |
| | |
| | If multiple hosts are specified, Crash will attempt |
| | to connect to all of them. The command will succeed |
| | if at least one connection is successful. |
+------------------------+-----------------------------------------------------+
| ``\dt`` | Print a list of tables. |
| | |
| | The list does not include tables in the ``sys`` and |
| | ``information_schema`` schema. |
+------------------------+-----------------------------------------------------+
| ``\format <FORMAT>`` | Specifies the output format of the SQL response. |
| | |
| | Same as ``--format`` command line option. |
| | |
| | Available ``<FORMAT>`` values are: ``tabular``, |
| | ``raw``, ``json``, ``json_row``, ``csv`` and |
| | ``mixed``. |
+------------------------+-----------------------------------------------------+
| ``\q`` | Quit the CrateDB shell. |
+------------------------+-----------------------------------------------------+
| ``\check <TYPE>`` | Query the ``sys`` tables for failing checks. |
| | |
| | ``TYPE`` can be one of the following: |
| | |
| | - not set (query for failing cluster and node |
| | checks) |
| | - ``nodes`` (query for failing node checks) |
| | - ``cluster`` (query for failing cluster checks) |
+------------------------+-----------------------------------------------------+
| ``\r <FILENAME>`` | Reads statements from ``<FILENAME>`` and execute |
| | them. |
+------------------------+-----------------------------------------------------+
| ``\sysinfo`` | Query the ``sys`` tables for system and cluster |
| | information. |
+------------------------+-----------------------------------------------------+
| ``\autocomplete`` | Turn autocomplete feature on or off. |
| | |
| | Works as a toggle. |
+------------------------+-----------------------------------------------------+
| ``\autocapitalize`` | Turn automatic capitalization for SQL keywords or |
| | off. |
| | |
| | Works as a toggle. |
+------------------------+-----------------------------------------------------+
38 changes: 38 additions & 0 deletions docs/compatibility.txt
View file
@@ -0,0 +1,38 @@
.. _compatibility:

=============
Compatibility
=============

.. CAUTION::

We recommend that you upgrade to the latest stable version of CrateDB
whenever possible. And we also recommend that you use the version of Crash
that is bundled with the version of CrateDB that you are using. This
greatly minimises the chances of experiencing compatibility issues.

CrateDB tries to maintain `backwards`_ and `forwards`_ compatibility. However,
this is not always possible.

Known compatibility issues:

- Due to `information schema`_ changes, Crash versions 0.19 and earlier
are not compatible with CrateDB versions 0.57 and later.

- For CrateDB versions 0.38.x and earlier, it is not possible to insert nested
arrays or nested objects via Crash. You must use `CrateDB REST endpoint`_ or a
`client library`_.

CrateDB versions 0.39 and later allow you to insert nested arrays using
`array constructors`_, and nested objects using `object literals`_.

- Crash client :ref:`commands <commands>` are only available since version 0.11
and later.

.. _array constructors: https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#array-constructor
.. _backwards: https://en.wikipedia.org/wiki/Backward_compatibility
.. _client library: https://crate.io/docs/crate/getting-started/en/latest/start-building/index.html
.. _CrateDB REST endpoint: https://crate.io/docs/crate/reference/en/latest/interfaces/http.html
.. _forwards: https://en.wikipedia.org/wiki/Forward_compatibility
.. _information schema: https://crate.io/docs/crate/reference/en/latest/general/information-schema.html
.. _object literals: https://crate.io/docs/crate/reference/en/latest/general/ddl/data-types.html#object-literals
0 crash.png → docs/crash.png
View file
File renamed without changes

0 comments on commit dbfcb05

Please sign in to comment.