1.. _command-line-interface: 2 3###################### 4Command Line Interface 5###################### 6 7.. include:: guide-common.rst.inc 8 9FoundationDB comes with a command line interface tool called ``fdbcli``. This document describes basic usage of ``fdbcli`` and the commands it supports. The use of ``fdbcli`` while :doc:`configuring <configuration>` and :doc:`administering <administration>` FoundationDB clusters is described in more detail in the documents on those topics and will be referenced as appropriate. 10 11.. _cli-invocation: 12 13Invocation at the Command Line 14============================== 15 16You can invoke ``fdbcli`` at the command line simply by typing it. For example:: 17 18 user@host$ fdbcli 19 Using cluster file `/etc/foundationdb/fdb.cluster'. 20 21 The database is available. 22 23 Welcome to the fdbcli. For help, type `help'. 24 fdb> 25 26This will result in ``fdbcli`` connecting to the :ref:`default cluster file <default-cluster-file>` (``/etc/foundationdb/fdb.cluster`` for Linux.) You can also specify a cluster file as an argument to ``fdbcli`` using the ``-C`` option. For further information, see :ref:`specifying-a-cluster-file`. 27 28Commands within ``fdbcli`` 29========================== 30 31The following commands can be issued from within ``fdbcli`` at the internal ``fdb>`` prompt: 32 33begin 34----- 35 36The ``begin`` command begins a new transaction. By default, ``fdbcli`` operates in autocommit mode. All operations are performed in their own transaction and are automatically committed. By explicitly beginning a transaction, successive operations are all performed as part of a single transaction. 37 38To commit the transaction, use the ``commit`` command. To discard the transaction, use the ``reset`` command. 39 40clear 41----- 42 43The ``clear`` command clears a key from the database. Its syntax is ``clear <KEY>``. This command succeeds even if the specified key is not present but may fail due to conflicts. 44 45Note that :ref:`characters can be escaped <cli-escaping>` when specifying keys (or values) in ``fdbcli``. 46 47clearrange 48---------- 49 50The ``clearrange`` command clears a range of keys from the database. Its syntax is ``clearrange <BEGINKEY> <ENDKEY>``. All keys between ``<BEGINKEY>`` (inclusive) and ``<ENDKEY>`` (exclusive) are cleared from the database. This command succeeds even if the specified range is empty but may fail due to conflicts. 51 52Note that :ref:`characters can be escaped <cli-escaping>` when specifying keys (or values) in ``fdbcli``. 53 54commit 55------ 56 57The ``commit`` command commits the current transaction. Any sets or clears executed after the start of the current transaction will be committed to the database. On success, the committed version number is displayed. If commit fails, the error is displayed and the transaction must be retried. 58 59configure 60--------- 61 62The ``configure`` command changes the database configuration. Its syntax is ``configure [new] [single|double|triple|three_data_hall|three_datacenter] [ssd|memory] [proxies=<N>] [resolvers=<N>] [logs=<N>]``. 63 64The ``new`` option, if present, initializes a new database with the given configuration rather than changing the configuration of an existing one. When ``new`` is used, both a redundancy mode and a storage engine must be specified. 65 66redundancy mode 67^^^^^^^^^^^^^^^ 68 69Redundancy modes define storage requirements, required cluster size, and resilience to failure. The available redundancy modes are: 70 71* ``single`` 72* ``double`` 73* ``triple`` 74* ``three_data_hall`` 75* ``three_datacenter`` 76 77For descriptions of redundancy modes, see :ref:`configuration-choosing-redundancy-mode`. 78 79storage engine 80^^^^^^^^^^^^^^^ 81 82The storage engine is responsible for durably storing data. FoundationDB has two storage engines: 83 84* ``ssd`` 85* ``memory`` 86 87For descriptions of storage engines, see :ref:`configuration-storage-engine`. 88 89process types 90^^^^^^^^^^^^^ 91 92A FoundationDB cluster employs server processes of different types. It automatically allocates these processes in default numbers appropriate for small-to-medium sized clusters. 93 94For large clusters, you can manually set the allocated number of processes of a given type. Valid process types are: 95 96* ``proxies`` 97* ``resolvers`` 98* ``logs`` 99 100Set the process using ``configure [proxies|resolvers|logs]=<N>``, where ``<N>`` is an integer greater than 0, or -1 to reset the value to its default. 101 102For recommendations on appropriate values for process types in large clusters, see :ref:`guidelines-process-class-config`. 103 104fileconfigure 105------------- 106 107The ``fileconfigure`` command is alternative to the ``configure`` command which changes the configuration of the database based on a json document. The command loads a JSON document from the provided file, and change the database configuration to match the contents of the JSON document. 108 109The format should be the same as the value of the ``configuration`` entry in status JSON without ``excluded_servers`` or ``coordinators_count``. Its syntax is ``fileconfigure [new] <FILENAME>``. 110 111"The ``new`` option, if present, initializes a new database with the given configuration rather than changing the configuration of an existing one. 112 113coordinators 114------------ 115 116The ``coordinators`` command is used to change cluster coordinators or description. Its syntax is ``coordinators auto|<ADDRESS...> [description=<DESC>]``. 117 118Addresses may be specified as a list of IP:port pairs (such as ``coordinators 10.0.0.1:4000 10.0.0.2:4000 10.0.0.3:4000``). If addresses are specified, the coordinators will be set to them. An ``fdbserver`` process must be running on each of the specified addresses. 119 120If ``auto`` is specified, coordinator addresses will be chosen automatically to support the configured redundancy level. Processes with class coordinator will be prioritized. (If the current set of coordinators are healthy and already support the configured redundancy level, nothing will be changed.) 121 122For more information on setting coordinators, see :ref:`configuration-changing-coordination-servers`. 123 124If ``description=<DESC>`` is specified, the description field in the cluster file is changed to ``<DESC>``, which must match ``[A-Za-z0-9_]+``. 125 126For more information on setting the cluster description, see :ref:`configuration-setting-cluster-description`. 127 128exclude 129------- 130 131The ``exclude`` command excludes servers from the database. Its syntax is ``exclude <ADDRESS...>``. If no addresses are specified, the command provides the set of excluded servers. 132 133For each IP address or IP:port pair in ``<ADDRESS...>``, the command adds the address to the set of excluded servers. It then waits until all database state has been safely moved off the specified servers. 134 135For more information on excluding servers, see :ref:`removing-machines-from-a-cluster`. 136 137exit 138---- 139 140The ``exit`` command exits ``fdbcli``. 141 142get 143--- 144 145The ``get`` command fetches the value of a given key. Its syntax is ``get <KEY>``. It displays the value of ``<KEY>`` if ``<KEY>`` is present in the database and ``not found`` otherwise. 146 147Note that :ref:`characters can be escaped <cli-escaping>` when specifying keys (or values) in ``fdbcli``. 148 149getrange 150-------- 151 152The ``getrange`` command fetches key-value pairs in a range. Its syntax is ``getrange <BEGINKEY> [ENDKEY] [LIMIT]``. It displays up to ``<LIMIT>`` keys and values for keys between ``<BEGINKEY>`` (inclusive) and ``<ENDKEY>`` (exclusive). If ``<ENDKEY>`` is omitted, then the range will include all keys starting with ``<BEGINKEY>``. ``<LIMIT>`` defaults to 25 if omitted. 153 154Note that :ref:`characters can be escaped <cli-escaping>` when specifying keys (or values) in ``fdbcli``. 155 156getrangekeys 157------------ 158 159The ``getrangekeys`` command fetches keys in a range. Its syntax is ``getrangekeys <BEGINKEY> [ENDKEY] [LIMIT]``. It displays up to ``<LIMIT>`` keys for keys between ``<BEGINKEY>`` (inclusive) and ``<ENDKEY>`` (exclusive). If ``<ENDKEY>`` is omitted, then the range will include all keys starting with ``<BEGINKEY>``. ``<LIMIT>`` defaults to 25 if omitted. 160 161Note that :ref:`characters can be escaped <cli-escaping>` when specifying keys (or values) in ``fdbcli``. 162 163help 164---- 165 166The ``help`` command provides information on specific commands. Its syntax is ``help <TOPIC>``, where ``<TOPIC>`` is any of the commands in this section, ``escaping``, or ``options``. The latter two topics are described below: 167 168.. _cli-escaping: 169 170help escaping 171^^^^^^^^^^^^^ 172 173``help escaping`` provides the following information on escaping keys and values within ``fdbcli``: 174 175When parsing commands, ``fdbcli`` considers a space to delimit individual tokens. To include a space in a single value, you may either enclose the token in quotation marks ``"``, prefix the space with a backslash ``\``, or encode the space as a hex character. 176 177To include a literal quotation mark in a token, precede it with a backslash ``\"``. 178 179To express a binary value, encode each byte as a two-digit hex value, preceded by ``\x`` (e.g. ``\x20`` for a space character, or ``\x0a\x00\x00\x00`` for a 32-bit, little-endian representation of the integer 10). 180 181All keys and values are displayed by ``fdbcli`` with non-printable characters and spaces encoded as two-digit hex bytes. 182 183.. _cli-options: 184 185help options 186^^^^^^^^^^^^ 187 188The following options are available for use with the ``option`` command: 189 190``ACCESS_SYSTEM_KEYS`` - Allows this transaction to read and modify system keys (those that start with the byte ``0xFF``). 191 192``CAUSAL_READ_RISKY`` - In the event of a fault or partition, the read version returned may not the last committed version potentially causing you to read outdated data. 193 194``CAUSAL_WRITE_RISKY`` - The transaction, if not self-conflicting, may be committed a second time after commit succeeds, in the event of a fault. 195 196``INITIALIZE_NEW_DATABASE`` - This is a write-only transaction which sets the initial configuration. 197 198``NEXT_WRITE_NO_WRITE_CONFLICT_RANGE`` - The next write performed on this transaction will not generate a write conflict range. As a result, other transactions which read the key(s) being modified by the next write will not conflict with this transaction. Care needs to be taken when using this option on a transaction that is shared between multiple threads. When setting this option, write conflict ranges will be disabled on the next write operation, regardless of what thread it is on. 199 200``PRIORITY_BATCH`` - Specifies that this transaction should be treated as low priority and that default priority transactions should be processed first. Useful for doing batch work simultaneously with latency-sensitive work. 201 202``PRIORITY_SYSTEM_IMMEDIATE`` - Specifies that this transaction should be treated as highest priority and that lower priority transactions should block behind this one. Use is discouraged outside of low-level tools. 203 204``READ_AHEAD_DISABLE`` - Disables read-ahead caching for range reads. Under normal operation, a transaction will read extra rows from the database into cache if range reads are used to page through a series of data one row at a time (i.e. if a range read with a one row limit is followed by another one row range read starting immediately after the result of the first). 205 206``READ_YOUR_WRITES_DISABLE`` - Reads performed by a transaction will not see any prior mutations that occurred in that transaction, instead seeing the value which was in the database at the transaction's read version. This option may provide a small performance benefit for the client, but also disables a number of client-side optimizations which are beneficial for transactions which tend to read and write the same keys within a single transaction. 207 208``RETRY_LIMIT`` - Set a maximum number of retries after which additional calls to ``onError`` will throw the most recently seen error code. Valid parameter values are ``[-1, INT_MAX]``. If set to -1, will disable the retry limit. Like all transaction options, the retry limit must be reset after a call to ``onError``. This behavior allows the user to make the retry limit dynamic. 209 210``TIMEOUT`` - Set a timeout in milliseconds which, when elapsed, will cause the transaction automatically to be cancelled. Valid parameter values are ``[0, INT_MAX]``. If set to 0, will disable all timeouts. All pending and any future uses of the transaction will throw an exception. The transaction can be used again after it is reset. Like all transaction options, a timeout must be reset after a call to ``onError``. This behavior allows the user to make the timeouts dynamic. 211 212 213include 214------- 215 216The ``include`` command permits previously excluded servers to rejoin the database. Its syntax is ``include all|<ADDRESS...>``. 217 218If ``all`` is specified, the excluded servers list is cleared. 219 220For each IP address or IP:port pair in ``<ADDRESS...>``, the command removes any matching exclusions from the excluded servers list. (A specified IP will match all ``IP:*`` exclusion entries). 221 222For information on adding machines to a cluster, see :ref:`adding-machines-to-a-cluster`. 223 224option 225------ 226 227The ``option`` command enables or disables an option. Its syntax is ``option <STATE> <OPTION> [ARG]``. Descriptions of :ref:`the available options <cli-options>` can be obtained within ``fdbcli`` by typing ``help options``. 228 229If ``<STATE>`` is ``on``, then ``<OPTION>`` will be enabled with optional parameter ``<ARG>``, if required. If ``<STATE>`` is ``off``, then ``<OPTION>`` will be disabled. 230 231If there is no active transaction, then the option will be applied to all operations as well as all subsequently created transactions (using ``begin``). 232 233If there is an active transaction (one created with ``begin``), then enabled options apply only to that transaction. Options cannot be disabled on an active transaction. 234 235Calling the ``option`` command with no parameters prints a list of all enabled options. 236 237reset 238----- 239 240The ``reset`` command resets the current transaction. Any sets or clears executed after the start of the active transaction will be discarded. 241 242rollback 243-------- 244 245The ``rollback`` command rolls back the current transaction. The active transaction will be discarded, including any sets or clears executed since the transaction was started. 246 247set 248--- 249 250The ``set`` command sets a value for a given key. Its syntax is ``set <KEY> <VALUE>``. If ``<KEY>`` is not already present in the database, it will be created. 251 252Note that :ref:`characters can be escaped <cli-escaping>` when specifying keys (or values) in ``fdbcli``. 253 254.. _cli-status: 255 256status 257------ 258 259The ``status`` command reports the status of the FoundationDB cluster to which ``fdbcli`` is connected. Its syntax is ``status [minimal|details|json]``. 260 261 262If the cluster is down, this command will print a diagnostic which may be useful 263in figuring out what is wrong. If the cluster is running, this command will 264print cluster statistics. 265 266status minimal 267^^^^^^^^^^^^^^ 268 269``status minimal`` will provide only an indication of whether the database is available. 270 271status details 272^^^^^^^^^^^^^^ 273 274``status details`` will provide load information for individual workers. 275 276For a detailed description of ``status`` output, see :ref:`administration-monitoring-cluster-status`. 277 278status json 279^^^^^^^^^^^ 280 281``status json`` will provide the cluster status in its JSON format. For a detailed description of this format, see :doc:`mr-status`. 282