diff --git a/DEVELOP.rst b/DEVELOP.rst index 423cfd19..cf89922f 100644 --- a/DEVELOP.rst +++ b/DEVELOP.rst @@ -5,12 +5,15 @@ Developer Guide Setup ===== -This project uses buildout_ to set up the development environment. +This project uses `buildout`_ to set up the development environment. To start things off, run:: $ python bootstrap.py +Your system python should be Python 3. If it isn't, try running `python3` +instead. If that doesn't exist, you will have to install Python 3. + Then, run:: $ ./bin/buildout -N @@ -22,7 +25,7 @@ Then to run your local crash, use:: Running Tests ============= -The tests are run using the zope.testrunner_:: +The tests are run using the `zope.testrunner`_:: $ ./bin/test @@ -33,8 +36,8 @@ You can run the tests against multiple Python interpreters with tox_:: $ ./bin/tox -To do this, you will need ``python2.7``, ``python3.3``, and ``pypy`` on your -``$PATH``. +To do this, you will need (for example) ``python3.3`` (any other interpreters +you want to test against) as well as ``pypy`` on your ``$PATH``. To run against a single interpreter, you can also do:: @@ -66,9 +69,9 @@ To create a new release, you must: - Create a tag by running ``./devtools/create_tag.sh`` -- Deploy to PyPI (see section below) +- Deploy to PyPI (see below) -- Archive docs for old releases (see section below) +- Archive docs for old releases (see below) PyPI Deployment --------------- @@ -77,11 +80,12 @@ To create the package use:: $ bin/py setup.py sdist bdist_wheel -Then, use twine_ to upload the package to PyPI_:: +Then, use twine_ to upload the package to `PyPI`_:: $ bin/twine upload dist/* -For this to work, you will need a personal PyPI account that is set up as a project admin. +For this to work, you will need a personal PyPI account that is set up as a +project admin. You'll also need to create a ``~/.pypirc`` file, like so:: @@ -94,7 +98,8 @@ You'll also need to create a ``~/.pypirc`` file, like so:: username= password= -Here, ```` and ```` should be replaced with your username and password, respectively. +Here, ```` and ```` should be replaced with your username +and password, respectively. If you want to check the PyPI description before uploading, run:: @@ -105,7 +110,7 @@ Archiving Docs Versions Check the `versions hosted on ReadTheDocs`_. -We should only be hosting the docs for `latest`, the last three minor release +We should only be hosting the docs for ``latest``, the last three minor release branches of the last major release, and the last minor release branch corresponding to the last two major releases. @@ -117,7 +122,7 @@ For example: - ``0.20`` Because this project has not yet had a major release, as of yet, there are no -major releases before `0` to include in this list. +major releases before ``0`` to include in this list. Sometimes you might find that there are multiple older releases that need to be archived. @@ -128,14 +133,15 @@ checkbox, and then saving. Standalone Deployment ===================== -The standalone executable is built and deployed by a Jenkins_ job. +The standalone executable is built and deployed by a `Jenkins`_ job. Writing Documentation ===================== The docs live under the ``docs`` directory. -The docs are written written with ReStructuredText_ and processed with Sphinx_. +The docs are written written with `ReStructuredText`_ and processed with +`Sphinx`_. Build the docs by running:: @@ -154,5 +160,5 @@ nothing special you need to do to get the live docs to update. .. _Sphinx: http://sphinx-doc.org/ .. _tox: http://testrun.org/tox/latest/ .. _twine: https://pypi.python.org/pypi/twine -.. _zope.testrunner: https://pypi.python.org/pypi/zope.testrunner/4.4.1 .. _versions hosted on ReadTheDocs: https://readthedocs.org/projects/crash/versions/ +.. _zope.testrunner: https://pypi.python.org/pypi/zope.testrunner/4.4.1 diff --git a/README.rst b/README.rst index b46479e2..d3c918ea 100644 --- a/README.rst +++ b/README.rst @@ -1,12 +1,12 @@ -===== -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 @@ -14,37 +14,47 @@ Crash :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. @@ -60,21 +70,22 @@ 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 @@ -82,17 +93,17 @@ 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 @@ -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 diff --git a/buildout.cfg b/buildout.cfg index 0904ed6f..45ab833c 100644 --- a/buildout.cfg +++ b/buildout.cfg @@ -23,6 +23,7 @@ eggs = crash recipe = hexagonit.recipe.download url = https://cdn.crate.io/downloads/releases/crate-${versions:crate_server}.tar.gz strip-top-level-dir = true +ignore-existing = true [test] relative-paths=true diff --git a/docs/autocomplete.png b/docs/autocomplete.png new file mode 100644 index 00000000..6cfd1799 Binary files /dev/null and b/docs/autocomplete.png differ diff --git a/docs/cli.txt b/docs/cli.txt deleted file mode 100644 index e7338982..00000000 --- a/docs/cli.txt +++ /dev/null @@ -1,189 +0,0 @@ -.. _cli: - -====================== -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. | -+---------------------------------------+--------------------------------------------------+ -| ``-U``, ``--username`` | The username to authenticate in the database | -+---------------------------------------+--------------------------------------------------+ -| ``-W``, ``--password`` | Force prompt for password. Otherwise it prompts | -| | for password automatically in case the server | -| | requires user authorization. | -+---------------------------------------+--------------------------------------------------+ -| ``-c COMMAND``, ``--command COMMAND`` | Execute the SQL statement and exit. | -+---------------------------------------+--------------------------------------------------+ -| ``--hosts HOSTS`` | The CrateDB hosts to connect to. | -+---------------------------------------+--------------------------------------------------+ -| ``--history HISTORY`` | The history file the CrateDB shell uses. | -+---------------------------------------+--------------------------------------------------+ -| ``--config CONFIG`` | Path to the configuration file which contains | -| | default values for Crash. | -| | Defaults to the `user configuration directory`_ | -| | of the operating system, which is e.g on Linux | -| | ``~/.config/Crate``, | -| | ``~/Library/Application Support/Crate`` on OSX | -| | or ``C:\\Users\user\AppData\Local\Crate\Crate`` | -| | on Windows. | -+---------------------------------------+--------------------------------------------------+ -| ``--format FORMAT`` | Specifies the output format of the SQL response. | -+---------------------------------------+--------------------------------------------------+ -| ``--version`` | Print the crash version and exit. | -+---------------------------------------+--------------------------------------------------+ -| ``--sysinfo`` | Print system and cluster information. | -+---------------------------------------+--------------------------------------------------+ -| ``-A`` , ``--no-autocomplete`` | Disable autocomplete of SQL keywords on startup. | -| | Autocomplete requires a minimum terminal | -| | height of 8 lines due to size of the dropdown | -| | overlay for suggestions. | -| | Disabling autocomplete removes this limitation. | -+---------------------------------------+--------------------------------------------------+ -| ``-a`` , ``--autocapitalize`` | Enable automatic capitalization of SQL keywords | -| | while typing. This feature is experimental and | -| | may be removed in future versions. | -+---------------------------------------+--------------------------------------------------+ -| ``--verify-ssl`` | Force verification of the SSL certificate of the | -| | server. | -+---------------------------------------+--------------------------------------------------+ -| ``--cert-file`` | Path to the client certificate file. | -+---------------------------------------+--------------------------------------------------+ -| ``--key-file`` | Path to the key file of the client certificate. | -+---------------------------------------+--------------------------------------------------+ -| ``--ca-cert-file`` | Path to CA certificate file (used to verify | -| | the certificate sent by the server. | -+---------------------------------------+--------------------------------------------------+ - -Example Usage -============= - -:: - - $ crash --hosts st1.crate.io:4200 st2.crate.io st3.crate.io \ - --format json \ - -c 'select * from sys.nodes' > output.json - - -Example Usage with SSL -====================== - -:: - - $ crash --hosts st1.crate.io:4200 st2.crate.io st3.crate.io \ - --format json \ - --verify-ssl true --cert-file /home/.certs/crateClient.crt --key-file /home/.certs/crateClient.key \ - --ca-cert-file /home/.certs/rootCA.crt -U sslUser \ - -c 'select * from sys.nodes' > output.json - - -===================== -Environment Variables -===================== - -Crash takes the following environment variables into account to select default -connection parameters. These can be helpful to avoid user-input prompts or any -other hard-coded cli parameter. - -:CRATEPW: Password to be used if CrateDB demands password authentication. - Keep in mind that for security reasons the usage of this variable is - not safe. - - -For example:: - - $ export CRATEPW=dustins-password - $ crash --hosts localhost:4200 \ - --username dustin \ - --format json \ - -c 'select * from sys.nodes' > output.json - -.. _commands: - -============== -Crash Commands -============== - -.. note:: - - Crash client commands are available since version ``0.11.x``! - -Crash has several client commands, which start with a backslash (``\``). - -You can get a list of commands by typing ``\?``: - -+----------------------+------------------------------------------------------------------------------------+ -| 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``, ``json_row``, ``csv`` | -| | and ``mixed`` | -| | | -| | see :ref:`formats` for details | -+----------------------+------------------------------------------------------------------------------------+ -| ``\q`` | Quit the CrateDB shell | -+----------------------+------------------------------------------------------------------------------------+ -| ``\check`` | Query the ``sys`` tables for failing cluster and node checks if no arguments are | -| | provided. | -| | | -| | The following arguments are allowed: | -| | - ``nodes``: to query the ``sys.node_checks`` table for failing node checks. | -| | - ``cluster``: to query the ``sys.checks`` table for failing cluster checks. | -+----------------------+------------------------------------------------------------------------------------+ -| ``\r `` | Reads statements from the given file and executes 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. | -+----------------------+------------------------------------------------------------------------------------+ - -=============== -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 , row(s) affected ( sec) - -If the SQL statement (``SELECT``) returns selected columns:: - - SUCCESS row(s) in set ( 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. - -``DURATION`` is the time it took to process the SQL statement on the server -from request to response. - - -.. _jq: http://stedolan.github.io/jq/ -.. _user configuration directory: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html - diff --git a/docs/commands.txt b/docs/commands.txt new file mode 100644 index 00000000..0505c154 --- /dev/null +++ b/docs/commands.txt @@ -0,0 +1,68 @@ +.. _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 ``, | Connect to ````. | +| | ``\connect `` | | +| | | +| | 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 `` | Specifies the output format of the SQL response. | +| | | +| | Same as ``--format`` command line option. | +| | | +| | Available ```` values are: ``tabular``, | +| | ``raw``, ``json``, ``json_row``, ``csv`` and | +| | ``mixed``. | ++------------------------+-----------------------------------------------------+ +| ``\q`` | Quit the CrateDB shell. | ++------------------------+-----------------------------------------------------+ +| ``\check `` | 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 `` | Reads statements from ```` 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. | ++------------------------+-----------------------------------------------------+ + + diff --git a/docs/compatibility.txt b/docs/compatibility.txt new file mode 100644 index 00000000..57e9b359 --- /dev/null +++ b/docs/compatibility.txt @@ -0,0 +1,37 @@ +.. _compatibility: + +============= +Compatibility +============= + +.. NOTE:: + + We recommend that you use the version of Crash that is bundled with the + version of CrateDB that you are using. This minimises the chances of + 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`_. + +.. note:: + + Crash client commands are available since version ``0.11.x``! + +.. _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 +.. _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 diff --git a/crash.png b/docs/crash.png similarity index 100% rename from crash.png rename to docs/crash.png diff --git a/docs/getting-started.txt b/docs/getting-started.txt new file mode 100644 index 00000000..6c3e0f40 --- /dev/null +++ b/docs/getting-started.txt @@ -0,0 +1,91 @@ +.. _getting-started: + +=============== +Getting Started +=============== + +.. rubric:: Table of Contents + +.. contents:: + :local: + +Install +======= + +Crash is bundled with `CrateDB`_ so there is typically no need to install it +yourself. + +.. TIP:: + + For manual installation instructions, consult the `PyPI overview`_. + +Run +=== + +If you are able to run the ``crate`` command (see `Running CrateDB`_), you +should be able to run the ``crash`` command. Both of these executable files +live inside the main CrateDB ``bin`` directory. + +If the CrateDB ``bin`` directory is on your `PATH`_, you can start Crash like +so:: + + sh$ crash + +Otherwise, locate the CrateDB directory, and run it like so:: + + sh$ ./bin/crash + +When ``crash`` is run without any additional arguments, it will attempt to +connect to ``localhost:4200``. To connect to another host, use the ``--hosts`` +flag. For example:: + + sh$ crash --host 198.51.100.1 + +If you are experiencing a connection error, try the ``--verbose`` flag:: + + sh$ crash --verbose + +When run with ``--verbose``, Crash will print useful information about +what it is doing to `STDOUT`_. This includes connection attempts and full stack +traces (in the case of an error). + +.. TIP:: + + For more help, see :ref:`run`. + +Query +===== + +When you run Crash, you will see something like this: + +.. image:: startup.png + :alt: A screenshot of Crash after startup + +This is an interactive `shell`_. You can type any CrateDB SQL query at the +``cr>`` prompt. + +Queries are autocompleted as you type: + +.. image:: autocomplete.png + :alt: A screenshot of Crash after executing a query + +Once you have entered your query, hit :kbd:`Enter` to run. + +You should see something like this: + +.. image:: query.png + :alt: A screenshot of Crash after executing a query + +.. TIP:: + + For more help, see :ref:`commands` or :ref:`formats`. + +.. _Command Line Arguments: https://crate.io/docs/projects/crash/en/stable/cli.html +.. _crate-python: https://pypi.python.org/pypi/crate/ +.. _CrateDB REST Endpoint: https://crate.io/docs/current/sql/rest.html +.. _PATH: https://en.wikipedia.org/wiki/PATH_(variable) +.. _PyPI overview: https://pypi.python.org/pypi/crash/ +.. _STDOUT: https://en.wikipedia.org/wiki/Standard_streams +.. _CrateDB: https://crate.io/products/cratedb/ +.. _Running CrateDB: https://crate.io/docs/crate/reference/en/latest/run.html +.. _shell: https://en.wikipedia.org/wiki/Shell_(computing) diff --git a/docs/index.txt b/docs/index.txt index efeb323e..b37a707c 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -1,15 +1,22 @@ .. _index: + ================= The CrateDB Shell ================= -The CrashDB Shell (aka ``crash``) provides a CLI for the CrateDB Server. +The CrashDB Shell (aka *Crash*) is an interactive `command-line interface`_ +(CLI) tool for interacting with CrateDB. .. rubric:: Table of Contents .. toctree:: :maxdepth: 2 - usage - cli + getting-started + run + commands formats + compatibility + +.. _PATH: https://en.wikipedia.org/wiki/PATH_(variable) +.. _command-line interface: https://en.wikipedia.org/wiki/Command-line_interface diff --git a/docs/query.png b/docs/query.png new file mode 100644 index 00000000..5c1ad9e3 Binary files /dev/null and b/docs/query.png differ diff --git a/docs/run.txt b/docs/run.txt new file mode 100644 index 00000000..b57bd496 --- /dev/null +++ b/docs/run.txt @@ -0,0 +1,194 @@ +.. _run: + +============= +Running Crash +============= + +This document covers the basics of running Crash from the `command-line`_. + +.. NOTE:: + + For help using Crash for the first time, check out :ref:`getting-started`. + +.. _options: + +Command-Line Options +==================== + +The ``crash`` executable supports multiple command-line options: + ++-------------------------------+----------------------------------------------+ +| Argument | Description | ++===============================+==============================================+ +| | ``-h``, | Show the help message and exit. | +| | ``--help`` | | ++-------------------------------+----------------------------------------------+ +| | ``-v``, | Print debug information to `STDOUT`_. | +| | ``--verbose`` | | ++-------------------------------+----------------------------------------------+ +| ``--version`` | Print the crash version and exit. | ++-------------------------------+----------------------------------------------+ +| ``--sysinfo`` | Print system and cluster information. | ++-------------------------------+----------------------------------------------+ +| | ``-U ``, | Authenticate as ````. | +| | ``--username `` | | ++-------------------------------+----------------------------------------------+ +| | ``-W``, | Force a password prompt. | +| | ``--password`` | | +| | If not set, a password prompt happens when | +| | required. | ++-------------------------------+----------------------------------------------+ +| | ``-c ``, | Execute the ```` and exit. | +| | ``--command `` | | ++-------------------------------+----------------------------------------------+ +| ``--hosts `` | Connect to ````. | +| | | +| | ```` 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. | ++-------------------------------+----------------------------------------------+ +| ``--history `` | Use ```` as a history file. | +| | | +| | Defaults to the ``crash_history`` file in | +| | the :ref:`user configuration directory | +| | `. | ++-------------------------------+----------------------------------------------+ +| ``--config `` | ```` specifies the configuration file. | +| | | +| | Defaults to the ``crash.cfg`` file in the | +| | :ref:`user configuration directory | +| | `. | ++-------------------------------+----------------------------------------------+ +| ``--format `` | ```` specifies the output format of | +| | the SQL response. | +| | | +| | Available formats are: ``tabular``, ``raw``, | +| | ``json``, ``json_row``, ``csv`` and | +| | ``mixed``. | ++-------------------------------+----------------------------------------------+ +| | ``-A`` , | Disable SQL keywords autocompletion. | +| | ``--no-autocomplete`` | | +| | Autocompletion requires a minimum terminal | +| | height of eight lines due to size of the | +| | dropdown overlay for suggestions. Disabling | +| | autocompletion removes this limitation. | ++-------------------------------+----------------------------------------------+ +| | ``-a`` , | Enable automatic capitalization of SQL | +| | ``--autocapitalize`` | keywords while typing. | +| | | +| | This feature is experimental and may be | +| | removed in future versions. | ++-------------------------------+----------------------------------------------+ +| ``--verify-ssl`` | Force the verification of the server SSL | +| | certificate. | ++-------------------------------+----------------------------------------------+ +| ``--cert-file `` | Use ```` as the client certificate | +| | file. | ++-------------------------------+----------------------------------------------+ +| ``--key-file `` | Use ```` as the client certificate | +| | key file. | ++-------------------------------+----------------------------------------------+ +| ``--ca-cert-file `` | Use ```` as the certificate | +| | authority (CA) certificate file (used to | +| | verify the server certificate). | ++-------------------------------+----------------------------------------------+ + +TODO: update crash --help output to match above + +TODO: blocked on python bug + +TODO: add comment for future authors to do the same + +Simple Example +-------------- + +:: + + $ crash --hosts st1.crate.io:4200 st2.crate.io st3.crate.io \ + --format json \ + -c 'select * from sys.nodes' > output.json + + +SSl Example +----------- + +:: + + $ crash --hosts st1.crate.io:4200 st2.crate.io st3.crate.io \ + --format json \ + --verify-ssl true --cert-file /home/.certs/crateClient.crt --key-file /home/.certs/crateClient.key \ + --ca-cert-file /home/.certs/rootCA.crt -U sslUser \ + -c 'select * from sys.nodes' > output.json + +.. _user-conf-dir: + +User Configuration Directory +============================ + +Defaults to the `user configuration directory`_ +of the operating system, which is e.g on Linux +``~/.config/Crate``, ``~/Library/Application +Support/Crate`` on OSX or +``C:\\Users\user\AppData\Local\Crate\Crate`` on +Windows. + +.. _env-vars: + +Environment Variables +===================== + +Crash takes the following environment variables into account to select default +connection parameters. These can be helpful to avoid user-input prompts or any +other hard-coded cli parameter. + +:CRATEPW: Password to be used if CrateDB demands password authentication. + Keep in mind that for security reasons the usage of this variable is + not safe. + + +For example:: + + $ export CRATEPW=dustins-password + $ crash --hosts localhost:4200 \ + --username dustin \ + --format json \ + -c 'select * from sys.nodes' > output.json + +.. _status-messages: + +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 , row(s) affected ( sec) + +If the SQL statement (``SELECT``) returns selected columns:: + + SUCCESS row(s) in set ( 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. + +``DURATION`` is the time it took to process the SQL statement on the server +from request to response. + +.. _command-line: https://en.wikipedia.org/wiki/Command-line_interface +.. _jq: http://stedolan.github.io/jq/ +.. _user configuration directory: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html +.. _STDOUT: https://en.wikipedia.org/wiki/Standard_streams diff --git a/docs/startup.png b/docs/startup.png new file mode 100644 index 00000000..580c92ff Binary files /dev/null and b/docs/startup.png differ diff --git a/docs/usage.txt b/docs/usage.txt deleted file mode 120000 index f35b70a2..00000000 --- a/docs/usage.txt +++ /dev/null @@ -1 +0,0 @@ -../src/crate/crash/usage.txt \ No newline at end of file diff --git a/setup.py b/setup.py index 11f00960..0eae19df 100644 --- a/setup.py +++ b/setup.py @@ -41,8 +41,7 @@ def read(path): long_description = ( - read('README.rst') + '\n' + - read(os.path.join('src', 'crate', 'crash', 'usage.txt')) + read('README.rst') ) versionf_content = read(os.path.join('src', 'crate', 'crash', '__init__.py')) diff --git a/src/crate/crash/usage.txt b/src/crate/crash/connect.txt similarity index 57% rename from src/crate/crash/usage.txt rename to src/crate/crash/connect.txt index 8c1e49cf..0bcbce40 100644 --- a/src/crate/crash/usage.txt +++ b/src/crate/crash/connect.txt @@ -1,33 +1,9 @@ -==================== -Installation & Usage -==================== +================ +Connection Tests +================ -If the package was installed using ``pip`` the shell can be started by -invoking ``crash`` in a terminal. We recommend to install it to the Python -user install directory to avoid unwanted dependency conflicts. - -:: - - pip install --user crash - - -.. note:: - If ``crash`` is installed in the Python user install directory please ensure - that ``~/.local/bin`` (Linux), or ``%APPDATA%\Python\\Scripts`` - (Windows) is added to the system path. - -``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 `Command Line Arguments`_. - -When you connect to a server that is not reachable or whose hostname cannot be resolved -you will get an error:: +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 +------------------------+-----------+---------+-----------+-----------...-+ @@ -47,7 +23,8 @@ you will get an error:: +-----------------------------+-----------+---------+-----------+-------------...-+ CONNECT ERROR -Successful connects will give you some information about the servers you connect to:: +Successful connects will give you some information about the servers you +connect to:: cr> \connect 127.0.0.1:44209; +------------------------+-----------+---------+-----------+---------+ @@ -57,8 +34,8 @@ Successful connects will give you some information about the servers you connect +------------------------+-----------+---------+-----------+---------+ CONNECT OK... -If you connect to more than one server, the command will succeed -if at least one server is reachable:: +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 300.300.300.300:4295; +-----------------------------+-----------+---------+-----------+-----------...-+ @@ -81,36 +58,10 @@ them without any special arguments like this:: +------------+ SELECT 1 row in set (... sec) -When the CrateDB shell is started with the option ``-v`` debugging information will be printed:: +When the CrateDB shell is started with the option ``-v`` debugging information +will be printed:: cr> select x from y; SQLActionException[TableUnknownException: Table 'doc.y' unknown] SQLActionException: NOT_FOUND 4041 TableUnknownException: Table 'doc.y' unknown ... - - -Limitations -=========== - -.. note:: - - Due to changes in the Information Schema of CrateDB, Crash versions <= 0.19 - are not compatible with CrateDB > 0.57. - -Nested Objects and Arrays -------------------------- - -.. note:: - - Since CrateDB 0.39.0 it is possible to use object and array literals and the - limitation does not apply when connecting to a CrateDB 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 `CrateDB REST -endpoint`_ or a client library like `crate-python`_ has to be used. - -The same also applies for arrays. - -.. _`CrateDB REST Endpoint`: https://crate.io/docs/current/sql/rest.html -.. _`Command Line Arguments`: https://crate.io/docs/projects/crash/en/stable/cli.html -.. _`crate-python`: https://pypi.python.org/pypi/crate/ diff --git a/src/crate/crash/tests.py b/src/crate/crash/tests.py index 3c030178..9bc7b6aa 100644 --- a/src/crate/crash/tests.py +++ b/src/crate/crash/tests.py @@ -96,7 +96,7 @@ def test_suite(): suite = unittest.TestSuite() flags = (doctest.NORMALIZE_WHITESPACE | doctest.ELLIPSIS) s = doctest.DocFileSuite( - 'usage.txt', 'output.txt', + 'connect.txt', 'output.txt', setUp=setUp, tearDown=tearDown, optionflags=flags,