.. _command-line-interface: ###################### Command Line Interface ###################### .. include:: guide-common.rst.inc FoundationDB 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 ` and :doc:`administering ` FoundationDB clusters is described in more detail in the documents on those topics and will be referenced as appropriate. .. _cli-invocation: Invocation at the Command Line ============================== You can invoke ``fdbcli`` at the command line simply by typing it. For example:: user@host$ fdbcli Using cluster file `/etc/foundationdb/fdb.cluster'. The database is available. Welcome to the fdbcli. For help, type `help'. fdb> This will result in ``fdbcli`` connecting to the :ref:`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`. Commands within ``fdbcli`` ========================== The following commands can be issued from within ``fdbcli`` at the internal ``fdb>`` prompt: advanceversion -------------- Forces the cluster to recover at the specified version. If the specified version is larger than the current version of the cluster, the cluster version is advanced to the specified version via a forced recovery. begin ----- The ``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. To commit the transaction, use the ``commit`` command. To discard the transaction, use the ``reset`` command. clear ----- The ``clear`` command clears a key from the database. Its syntax is ``clear ``. This command succeeds even if the specified key is not present but may fail due to conflicts. Note that :ref:`characters can be escaped ` when specifying keys (or values) in ``fdbcli``. clearrange ---------- The ``clearrange`` command clears a range of keys from the database. Its syntax is ``clearrange ``. All keys between ```` (inclusive) and ```` (exclusive) are cleared from the database. This command succeeds even if the specified range is empty but may fail due to conflicts. Note that :ref:`characters can be escaped ` when specifying keys (or values) in ``fdbcli``. commit ------ The ``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. configure --------- The ``configure`` command changes the database configuration. Its syntax is ``configure [new|tss] [single|double|triple|three_data_hall|three_datacenter] [ssd|memory] [grv_proxies=] [commit_proxies=] [resolvers=] [logs=] [count=] [perpetual_storage_wiggle=] [perpetual_storage_wiggle_locality=<:|0>] [storage_migration_type={disabled|aggressive|gradual}] [tenant_mode={disabled|optional_experimental|required_experimental}]``. The ``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. The ``tss`` option, if present, changes the Testing Storage Server (TSS) configuration for a cluster. When used for the first time, both a count and a storage engine must be specified. For more details, see :ref:`testing-storage-server`. redundancy mode ^^^^^^^^^^^^^^^ Redundancy modes define storage requirements, required cluster size, and resilience to failure. The available redundancy modes are: * ``single`` * ``double`` * ``triple`` * ``three_data_hall`` * ``three_datacenter`` For descriptions of redundancy modes, see :ref:`configuration-choosing-redundancy-mode`. storage engine ^^^^^^^^^^^^^^^ The storage engine is responsible for durably storing data. FoundationDB has two storage engines: * ``ssd`` * ``memory`` For descriptions of storage engines, see :ref:`configuration-storage-engine`. process types ^^^^^^^^^^^^^ A FoundationDB cluster employs server processes of different types. It automatically allocates these processes in default numbers appropriate for small-to-medium sized clusters. For large clusters, you can manually set the allocated number of processes of a given type. Valid process types are: * ``grv_proxies`` * ``commit_proxies`` * ``resolvers`` * ``logs`` Set the process using ``configure [grv_proxies|commit_proxies|resolvers|logs]=``, where ```` is an integer greater than 0, or -1 to reset the value to its default. For recommendations on appropriate values for process types in large clusters, see :ref:`guidelines-process-class-config`. perpetual storage wiggle ^^^^^^^^^^^^^^^^^^^^^^^^ ``perpetual_storage_wiggle`` sets the value speed (a.k.a., the number of processes that the Data Distributor should wiggle at a time). Currently, only 0 and 1 are supported. The value 0 means to disable the perpetual storage wiggle. ``perpetual_storage_wiggle_locality`` sets the process filter for wiggling. The processes that match the given locality key and locality value are only wiggled. The value 0 will disable the locality filter and matches all the processes for wiggling. For more details, see :ref:`perpetual-storage-wiggle`. storage migration type ^^^^^^^^^^^^^^^^^^^^^^ Set the storage migration type, or how FDB should migrate to a new storage engine if the value is changed. The default is ``disabled``, which means changing the storage engine will not be possible. * ``disabled`` * ``gradual`` * ``aggressive`` ``gradual`` replaces a single storage at a time when the ``perpetual storage wiggle`` is active. This requires the perpetual storage wiggle to be set to a non-zero value to actually migrate storage servers. It is somewhat slow but very safe. This is the recommended method for all production clusters. ``aggressive`` tries to replace as many storages as it can at once, and will recruit a new storage server on the same process as the old one. This will be faster, but can potentially hit degraded performance or OOM with two storages on the same process. The main benefit over ``gradual`` is that this doesn't need to take one storage out of rotation, so it works for small or development clusters that have the same number of storage processes as the replication factor. Note that ``aggressive`` is not exclusive to running the perpetual wiggle. ``disabled`` means that if the storage engine is changed, fdb will not move the cluster over to the new storage engine. This will disable the perpetual wiggle from rewriting storage files. consistencycheck ---------------- The ``consistencycheck`` command enables or disables consistency checking. Its syntax is ``consistencycheck [on|off]``. Calling it with ``on`` enables consistency checking, and ``off`` disables it. Calling it with no arguments displays whether consistency checking is currently enabled. You must be running an ``fdbserver`` process with the ``consistencycheck`` role to perform consistency checking. coordinators ------------ The ``coordinators`` command is used to change cluster coordinators or description. Its syntax is ``coordinators auto| [description=]``. Addresses 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. If ``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.) For more information on setting coordinators, see :ref:`configuration-changing-coordination-servers`. If ``description=`` is specified, the description field in the cluster file is changed to ````, which must match ``[A-Za-z0-9_]+``. For more information on setting the cluster description, see :ref:`configuration-setting-cluster-description`. createtenant ------------ The ``createtenant`` command is used to create new tenants in the cluster. Its syntax is ``createtenant ``. The tenant name can be any byte string that does not begin with the ``\xff`` byte. If the tenant already exists, ``fdbcli`` will report an error. defaulttenant ------------- The ``defaulttenant`` command configures ``fdbcli`` to run its commands without a tenant. This is the default behavior. The active tenant cannot be changed while a transaction (using ``begin``) is open. deletetenant ------------ The ``deletetenant`` command is used to delete tenants from the cluster. Its syntax is ``deletetenant ``. In order to delete a tenant, it must be empty. To delete a tenant with data, first clear that data using the ``clear`` command. If the tenant does not exist, ``fdbcli`` will report an error. exclude ------- The ``exclude`` command excludes servers from the database or marks them as failed. Its syntax is ``exclude [failed] [] [locality_dcid:] [locality_zoneid:] [locality_machineid:] [locality_processid:] or any locality``. If no addresses are specified, the command provides the set of excluded and failed servers and localities. For each IP address or IP:port pair in ```` or locality (which include anything set on LocalityData like dcid, zoneid, machineid, processid), the command adds the address/locality to the set of excluded servers and localities. It then waits until all database state has been safely moved off the specified servers. If the ``failed`` keyword is specified, the address is marked as failed and added to the set of failed servers. It will not wait for the database state to move off the specified servers. For more information on excluding servers, see :ref:`removing-machines-from-a-cluster`. Warning about potential dataloss ``failed`` option: if a server is the last one in some team(s), excluding it with ``failed`` will lose all data in the team(s), and hence ``failed`` should only be set when the server(s) have permanently failed. In the case all servers of a team have failed permanently, excluding all the servers will clean up the corresponding keyrange, and fix the invalid metadata. The keyrange will be assigned to a new team as an empty shard. exit ---- The ``exit`` command exits ``fdbcli``. fileconfigure ------------- The ``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. The 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] ``. "The ``new`` option, if present, initializes a new database with the given configuration rather than changing the configuration of an existing one. force_recovery_with_data_loss ----------------------------- The ``force_recovery_with_data_loss`` command will recover a multi-region database to the specified datacenter. Its syntax is ``force_recovery_with_data_loss ``. It will likely result in the loss of the most recently committed mutations and is intended to be used if the primary datacenter has been lost. This command will change the :ref:`region configuration ` to have a positive priority for the chosen ``DCID`` and a negative priority for all other ``DCIDs``. It will also set ``usable_regions`` to 1. If the database has already recovered, this command does nothing. get --- The ``get`` command fetches the value of a given key. Its syntax is ``get ``. It displays the value of ```` if ```` is present in the database and ``not found`` otherwise. Note that :ref:`characters can be escaped ` when specifying keys (or values) in ``fdbcli``. getrange -------- The ``getrange`` command fetches key-value pairs in a range. Its syntax is ``getrange [ENDKEY] [LIMIT]``. It displays up to ```` keys and values for keys between ```` (inclusive) and ```` (exclusive). If ```` is omitted, then the range will include all keys starting with ````. ```` defaults to 25 if omitted. Note that :ref:`characters can be escaped ` when specifying keys (or values) in ``fdbcli``. getrangekeys ------------ The ``getrangekeys`` command fetches keys in a range. Its syntax is ``getrangekeys [ENDKEY] [LIMIT]``. It displays up to ```` keys for keys between ```` (inclusive) and ```` (exclusive). If ```` is omitted, then the range will include all keys starting with ````. ```` defaults to 25 if omitted. Note that :ref:`characters can be escaped ` when specifying keys (or values) in ``fdbcli``. gettenant --------- The ``gettenant`` command fetches metadata for a given tenant and displays it. Its syntax is ``gettenant ``. Included in the output of this command are the ``id`` and ``prefix`` assigned to the tenant. If the tenant does not exist, ``fdbcli`` will report an error. getversion ---------- The ``getversion`` command fetches the current read version of the cluster or currently running transaction. help ---- The ``help`` command provides information on specific commands. Its syntax is ``help ``, where ```` is any of the commands in this section, ``escaping``, or ``options``. The latter two topics are described below: .. _cli-escaping: help escaping ^^^^^^^^^^^^^ ``help escaping`` provides the following information on escaping keys and values within ``fdbcli``: When 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. To include a literal quotation mark in a token, precede it with a backslash ``\"``. To 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). All keys and values are displayed by ``fdbcli`` with non-printable characters and spaces encoded as two-digit hex bytes. .. _cli-options: help options ^^^^^^^^^^^^ The following options are available for use with the ``option`` command: ``ACCESS_SYSTEM_KEYS`` - Allows this transaction to read and modify system keys (those that start with the byte ``0xFF``). ``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. ``CAUSAL_WRITE_RISKY`` - The transaction, if not self-conflicting, may be committed a second time after commit succeeds, in the event of a fault. ``INITIALIZE_NEW_DATABASE`` - This is a write-only transaction which sets the initial configuration. ``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. ``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. ``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. ``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). ``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. ``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. ``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. include ------- The ``include`` command permits previously excluded or failed servers/localities to rejoin the database. Its syntax is ``include [failed] all|[] [locality_dcid:] [locality_zoneid:] [locality_machineid:] [locality_processid:] or any locality``. The ``failed`` keyword is required if the servers were previously marked as failed rather than excluded. If ``all`` is specified, the excluded servers and localities list is cleared. This will not clear the failed servers and localities list. If ``failed all`` or ``all failed`` is specified, the failed servers and localities list is cleared. This will not clear the excluded servers and localities list. For each IP address or IP:port pair in ```` or locality, the command removes any matching exclusions from the excluded servers/localities list. (A specified IP will match all ``IP:*`` exclusion entries). For information on adding machines to a cluster, see :ref:`adding-machines-to-a-cluster`. kill ---- The ``kill`` command attempts to kill one or more processes in the cluster. ``kill`` With no arguments, ``kill`` populates the list of processes that can be killed. This must be run prior to running any other ``kill`` commands. ``kill list`` Displays all known processes. This is only useful when the database is unresponsive. ``kill `` Attempts to kill all specified processes. Each address should include the IP and port of the process being targeted. ``kill all`` Attempts to kill all known processes in the cluster. listtenants ----------- The ``listtenants`` command prints the names of tenants in the cluster. Its syntax is ``listtenants [BEGIN] [END] [LIMIT]``. By default, the ``listtenants`` command will print up to 100 entries from the entire range of tenants. A narrower sub-range can be printed using the optional ``[BEGIN]`` and ``[END]`` parameters, and the limit can be changed by specifying an integer ``[LIMIT]`` parameter. lock ---- The ``lock`` command locks the database with a randomly generated lockUID. maintenance ----------- The ``maintenance`` command marks a particular zone ID (i.e. fault domain) as being under maintenance. Its syntax is ``maintenance [on|off] [ZONEID] [SECONDS]``. A zone that is under maintenance will not have data moved away from it even if processes in that zone fail. In particular, this means the cluster will not attempt to heal the replication factor as a result of failures in the maintenance zone. This is useful when the amount of time that the processes in a fault domain are expected to be absent is reasonably short and you don't want to move data to and from the affected processes. Running this command with no arguments will display the state of any current maintenance. Running ``maintenance on `` will turn maintenance on for the specified zone. A duration must be specified for the length of maintenance mode. Running ``maintenance off`` will turn off maintenance mode. option ------ The ``option`` command enables or disables an option. Its syntax is ``option