# 5.4. quasardb shell¶

## 5.4.1. Introduction¶

The quasardb shell is a command line tool that enables you to add, update, delete and retrieve entries from a quasardb node or cluster. The shell can be used interactively and non-interactively. In interactive mode, the user enters commands to be executed on the node. Feedback is provided to indicate failure. In non-interactive mode, a single command - supplied as a parameter - is executed and the program exits.

By default qdbsh will attempt to connect in interactive mode to a qdbd daemon running on 127.0.0.1:2836. If this is not the case - for example if your qdbd daemon runs on 192.168.1.1 and listens on the port 303 - you will need to pass the address and port as a qdb:// URI string, shown below:

qdbsh qdb://192.168.1.1:303


When connecting to a cluster, any node within the cluster is capable of serving requests. There is no “master” or “preferred” node. There is no performance impact of choosing one node instead of the other, except, perhaps, the physical capabilities of the node.

## 5.4.2. Quick Reference¶

### Command line options¶

Option Usage Default
-h, --help display help
-v, --version display quasardb version
-c run a qdb command
-l, --list-commands list available commands
--cluster cluster URI qdb://127.0.0.1:2836
--color-output color output mode automatic
--user-credentials-file path to the file containing the user’s name and secret key used for connection
--cluster-public-key-file path to the file containing the public key of the cluster to connect to

### Commands¶

Command Usage
help display the help
exit exit the shell (interactive mode only)
blob_compare_and_swap alias content comparand atomically compare and swap the Blob with the comparand
blob_get alias return the content of the Blob
blob_get_and_update alias content atomically get and update the Blob
blob_put alias content create a new Blob; fails if Blob already exists
blob_remove_if alias comparand remove the Blob if the value matches the comparand
blob_scan pattern max_count scan ALL blobs on the WHOLE cluster for the given pattern
blob_scan_regex pattern max_count scan ALL blobs on the WHOLE cluster for the given regular expression pattern
blob_update alias content update an existing Blob or creates a new Blob
cluster_purge_all remove ALL entries on the WHOLE cluster (dangerous!)
cluster_purge_cache remove ALL cached data on the WHOLE cluster
cluster_trim remove unused versions of entries from the cluster
cluster_wait_for_stabilization timeout_in_millliseconds wait for the stabilization of the cluster
cluster_status timeout_in_seconds cluster_uri print status information about a cluster
expires_at alias expiry set the absolute expiry time of the entry
expires_from_now alias delta set the expiry time of the entry to seconds relative to now
get_expiry alias return the absolute expiry time of the entry
get_type alias return the type of the entry
remove alias remove the entry from the cluster
int_add alias value atomically increment the Integer by the value
int_get alias return the value of the Integer
int_put alias value create a new Integer; fails if Integer already exists
int_update alias value update an existing Integer or create a new Integer
node_config host return the node configuration as a JSON string
node_status host return the node status as a JSON string
node_stop host reason shut down the quasardb daemon on a host
node_topology host reason return the node topology as a JSON string
deque_back alias return the value at the back of the Deque
deque_front alias return the value at the front of the Deque
deque_pop_back alias remove and return the value from the back of the Deque
deque_pop_front alias remove and return the value from the front of the Deque
deque_push_back alias content add a value to the back of the Deque
deque_push_front alias content add a value to the front of the Deque
deque_size alias return the size of the Deque
attach_tag alias tag add a tag to an entry
attach_tags alias tag1 [ tag2 … ] add tags to an entry
detach_tag alias tag remove a tag from an entry
detach_tags alias tag1 [ tag2 … ] remove tags from an entry
get_tagged tag get entries with the given tag
get_tagged_count tag get an approximative count of entries with the given tag
get_tags tag get tags for the given entry
has_tag alias tag return true if the entry has the tag
stream_from_buffer alias content write content into a stream
stream_to_buffer alias dump the content of a stream
stream_from_file alias file_path load a file and adds it into a file
stream_to_file alias file_path dump the content of a stream into a file
version display the quasardb version
show show the columns and their types for the given timeseries
select execute a select query
find execute a find query
prefix_get prefix max_count return aliases of all entries with aliases starting with the given prefix
suffix_get suffix max_count return aliases of all entries with aliases ending with the given suffix

## 5.4.3. Interactive mode¶

Use qdbsh interactive mode to enter as many commands as needed. The shell provides you with feedback upon success and failure or displays the content of retrieved entries.

Unless otherwise specified, qdbsh assumes the daemon is running on localhost and on the port 2836.

Once qdbsh has connected to a cluster, the following prompt is displayed:

qdbsh >


This means the shell is ready to accept commands. Only one command at a time may be specified.

A command is executed as soon as Enter is pressed and cannot be canceled or rolled back.

To exit the shell, enter the command exit. To list the available commands, type help. For the list of supported commands, see Commands.

If the command is expected to output content on success (such as the get command), it will be printed on the standard output stream. Binary content may not be printed correctly and may even corrupt your terminal display.

If the previous command executes successfully, the prompt shows:

qdbsh >


If the previous command fails, the prompt turns into:

qdbsh!>


As of quasardb 2.0.0, qdbsh in interactive mode supports tab completion and command history (using the Up/Down and PgUp/PgDn keys).

### Examples¶

Add a new Blob named “alias” whose content is “content” and print it:

qdbsh > blob_put alias content
qdbsh > blob_get alias
content
qdbsh >


Remove an entry named “alias”:

qdbsh > remove alias
qdbsh >


## 5.4.4. Non-interactive mode¶

Use qdbsh non-interactive mode to run one command without waiting for any input. Non-interactive mode supports standard input and output and can be integrated in a tool chain à la Unix. Performance-wise, non-interactive mode implies establishing and closing a connection to the quasardb cluster every time the qdbsh executable is run.

The command to be executed is supplied as an argument to the -c parameter. For the list of supported commands, see Commands.

When successful, the result of the command will be printed on the standard output stream and the shell will exit with the code 0. Most commands produce no output when successful (silent success).

In case of error, the shell will output an error message on the standard error output stream and will exit with the code 1.

### Examples¶

Unless otherwise specified, qdbsh assumes the daemon is running on localhost and on the port 2836.

Save the content of a Blob named “biography” in a text file named “biography.txt”:

qdbsh -c blob_get biography > biography.txt


Compress a file named “myfile”, then add its content to an entry named “myfile” on the quasardb node at 192.168.1.1:

bzip2 -c myfile | qdbsh qdb://192.168.1.1:2836 -c blob_put myfile


## 5.4.5. Reference¶

### Options¶

Parameters can be supplied in any order and are prefixed with --. The arguments format is parameter dependent. See Interactive mode for more information.

-h, --help

Displays basic usage information.

-v, --version

Displays the version information for the quasardb shell.

-c <command>

Specifies a command to run in non-interactive mode. For the list of supported commands, see Commands.

Argument
The command and required parameters for the command.
Example

If the qdbd daemon is on localhost and listens on port 3001 and we want to add an entry:

qdbsh qdb://127.0.0.1:3001 -c blob_put title "There and Back Again: A Hobbit's Tale"

-l, --list-commands

Lists all available shell commands.

--cluster <uri>

Specifies a URI to the cluster to which the shell should connect.

--color-output <mode>

Specifies the color output mode when using interactive mode of the shell. Possible values are: yes, no, automatic.

--user-credentials-file <filepath>

Specifies a path to the file containing the user’s name and secret key used for connection.

--cluster-public-key-file <filepath>

Specifies a path to the file containing the public key of the cluster to connect to.

### Commands¶

A command generally requires one or several arguments. Each argument is separated by one or several space characters.

help

Display basic usage information and lists all available commands.

exit

Exit the shell.

cls

Clears the screen.

show

Display the content of a time series table.

select <query>

Run a select query on the database. When quoting identifiers, you need to escape double quotes.

Param query: (string) query tabular result of the query
find <query>

Run a find query on the database.

Param query: (string) query list of aliases matching the query
blob_compare_and_swap <alias> <content> <comparand>

Atomically compare the value of an existing Blob with the comparand and replace it with the new content in case of match. The Blob must already exist.

Param alias: Param content: (string) the alias of the Blob (string) the new content of the Blob (string) the value to compare against content (string) the original content of the Blob or an error message

Note

• The alias must not contain the space character and its length must be below 1024.
• The new content must only be printable characters. This is only a qdbsh restriction.
• There must be one space and only one space between the comparand and the content.
• There is no practical limit to the comparand length. All characters until the end of the input are used for the comparand, including space characters.
blob_get <alias>

Retrieve an existing Blob from the cluster and print it to standard output.

Param alias: (string) the alias of the Blob (string) the content of the Blob or an error message
Example

Retrive a Blob whose alias is “alias” and whose content is the string “content”:

qdbsh > blob_get alias
content
qdbsh >


Note

• The alias must not contain the space character.
• The alias must not be longer than 1024 characters.
blob_get_and_update <alias> <content>

Atomically get the previous value of a Blob and replace it with the specified content. The Blob must already exist.

Param alias: (string) the alias of the Blob (string) the new content of the Blob (string) the content of the Blob or an error message
Example

Add a Blob whose alias is “myentry”, and whose content is the string “MagicValue”:

blob_put myentry MagicValue


Update the content to “VeryMagicValue” and get the previous content:

blob_get_and_update myentry MagicValue
VeryMagicValue


Note

• The alias must not contain the space character and its length must be below 1024.
• There must be one space and only one space between the alias and the content.
• There is no practical limit to the content length. All characters until the end of the input are added to the content, including space characters.
blob_put <alias> <content>

Add a new Blob to the cluster. The Blob must not already exist.

Param alias: (string) the alias of the Blob (string) the content of the Blob nothing if successful, an error message otherwise
Example

Add a Blob whose alias is “myentry” and whose content is the string “MagicValue”:

blob_put myentry MagicValue


Note

• The alias must not contain the space character and its length must be below 1024.
• There must be one space and only one space between the alias and the content.
• There is no practical limit to the content length. All characters until the end of the input are added to the content, including space characters.
blob_remove_if <alias> <comparand>

Atomically compare the Blob with the comparand and remove it in case of match.

Param alias: Param comparand: (string) The alias of the Blob (string) The value to compare against the content of the Blob true if the Blob was successfully removed, false otherwise
blob_scan <pattern> <max_count>

Scan ALL blobs on the WHOLE cluster for the given pattern and returns the aliases of matching blobs. The pattern is compared byte-wise.

Param pattern: Param max_count: (string) The pattern to be searched for, byte-wise (int) maximum number of results list of aliases
blob_scan_regex <pattern> <max_count>

Scan ALL blobs on the WHOLE cluster for the given regular expression and returns the aliases of matching blobs.

Param pattern: Param max_count: (string) The regular expression to be searched for (int) maximum number of results list of aliases
blob_update <alias> <content>

Add or update a Blob. If the Blob doesn’t exist it is created, otherwise it is changed to the new specified value.

Param alias: (string) the alias of the Blob (string) the content of the Blob nothing if successful, an error message otherwise
Example

Add a Blob whose alias is “myentry” and whose content is the string “MagicValue”:

blob_update myentry MagicValue


Change the value of the Blob “myentry” to the content “MagicValue2”:

blob_update myentry MagicValue2


Note

• The alias cannot contain the space character and its length must be below 1024.
• There must be one space and only one space between the alias and the content.
• There is no practical limit to the content length and all characters until the end of the input will be added to the content, including space characters.
cluster_purge_all

Remove all entries from the cluster. This command is not atomic. When activated:

1. Replication and migration is stopped.
2. The directories containing data and metadata are removed.
3. All entries are cleared from memory.
4. Replication and migration are restarted.
Return: nothing if successful, an error message otherwise

Caution

All entries will be deleted and will not be recoverable. If the cluster is unstable, the command may not be executed by all nodes. The command will nevertheless return success.

cluster_purge_cache

Remove all cached data from the cluster. This command is not atomic. When activated:

1. Replication and migration is stopped.
2. All entries are cleared from memory.
3. Replication and migration are restarted.
Return: nothing if successful, an error message otherwise
cluster_wait_for_stabilization <timeout_in_millliseconds>

Wait for the stabilization of the cluster.

Param timeout_in_millliseconds:
(int) timeout for the stabilization operation, in milliseconds
Return:nothing if successful, an error message otherwise
cluster_trim

Remove unused versions of entries from the cluster, freeing up disk space.

Return: nothing if successful, an error message otherwise
cluster_status <timeout_in_seconds> <cluster_uri>

Print status information about a cluster

Return: information about the cluster status
expires_at <alias> <expiry>

Set the expiry time of an existing entry from the quasardb cluster.

Param alias: (string) A string with the alias of the entry for which the expiry must be set (string) The absolute time at which the entry expires nothing if successful, an error message otherwise
expires_from_now <alias> <delta>

Set the expiry time of an existing entry from the quasardb cluster.

Param alias: (string) the alias of the entry for which the expiry must be set (string) A time, relative to the call time, after which the entry expires nothing if successful, an error message otherwise
get_expiry <alias>

Retrieve the expiry time of an existing entry.

Param alias: (string) the alias of the entry (string) the expiry time of the alias
get_metadata <alias>

Retrieve the metadata of an existing entry.

Param alias: (string) the alias of the entry (string) the metadata of the entry
get_type <alias>

Retrieve the type of an existing entry.

Param alias: (string) the alias of the entry (string) the type of the entry
remove <alias>

Remove an entry from the cluster. The entry must already exist.

Param alias: (string) the alias of the entry to delete nothing if successful, an error message otherwise
Example

Removes an entry named “obsolete”:

remove obsolete

int_add <alias> <value>

Atomically increment the Integer by the value

Param alias: (string) the alias of the Integer (int) the value to add to the Integer the value of the Integer after the addition
int_get <alias>

Return the value of the Integer

Param alias: (string) the alias of the Integer (int) the value of the Integer
int_put <alias> <value>

Add a new Integer to the cluster. The Integer must not already exist.

Param alias: (string) the alias of the Integer (int) the value of the Integer nothing if successful, an error message otherwise
int_update <alias> <value>

Add or update an Integer. If the Integer doesn’t exist it is created, otherwise it is changed to the new specified value.

Param alias: (string) the alias of the Integer (int) the content of the Integer nothing if successful, an error message otherwise
node_config <host>

Return the node configuration as a JSON string

Param host: (string) The node designated by its host and port number (e.g. “127.0.0.1:2836”) (string) The node configuration
node_status <host>

Return the node status as a JSON string.

Param host: (string) The node designated by its host and port number (e.g. “127.0.0.1:2836”) (string) node status
node_topology <host>

Return the node topology (list of predecessors and successors) as a JSON string.

Param host: (string) The node designated by its host and port number (e.g. “127.0.0.1:2836”) (string) node topology
node_stop <host>

Stop the node designated by its host and port number. The stop is generally effective within a few seconds of being issued, which allows inflight calls to complete successfully.

Param host: (string) The node designated by its host and port number (e.g. “127.0.0.1:2836”)
deque_back <alias>

Get the value at the end of the Deque.

Param alias: (string) the alias of the Deque (string) the value of the last item in the Deque
deque_front <alias>

Get the value at the start of the Deque.

Param alias: (string) the alias of the Deque (string) the value of the first item in the Deque
deque_pop_back <alias>

Remove the value at the end of the Deque and return its value.

Param alias: (string) the alias of the Deque (string) the value of the last item in the Deque
deque_pop_front <alias>

Remove the value at the start of the Deque and return its value.

Param alias: (string) the alias of the Deque (string) the value of the first item in the Deque
deque_push_back <alias> <content>

Append the value to the Deque.

Param alias: (string) the alias of the Deque (string) the value to add to the end of the Deque nothing if successful, an error message otherwise
deque_push_front <alias> <content>

Prepend the value to the Deque.

Param alias: (string) the alias of the Deque (string) the value to add to the start of the Deque nothing if successful, an error message otherwise
deque_size <alias>

Return the size of the Deque.

Param alias: (string) the alias of the Deque number of elements in the Deque
attach_tag <alias> <tag>

Add a tag to the specified entry.

Param alias: (string) the alias of the entry (string) the tag to assign to the entry
attach_tags <alias> <tag> [ <tag> ... ]

Add tags to the specified entry.

Param alias: (string) the alias of the entry (string) the tag to assign to the entry
get_tagged <tag>

Get a list of entries tagged with the specified tag.

Param tag: (string) the tag to search for list of aliases
get_tagged_count <tag>

Get an approximative count of entries tagged with the specified tag.

Param tag: (string) the tag to search for approximative number of tagged entries
get_tags <alias>

Get a list of tags for the specified entry.

Param alias: (string) the entry to check list of aliases
has_tag <alias> <tag>

Determine if an entry has a specified tag.

Param alias: (string) the alias of the entry (string) the tag to compare against the entry
prefix_get <prefix> <max_count>

Get aliases of all entries with aliases starting with the given prefix.

Param prefix: Param max_count: (string) prefix to search for (int) maximum number of results list of aliases
suffix_get <suffix> <max_count>

Get aliases of all entries with aliases ending with the given suffix.

Param suffix: Param max_count: (string) suffix to search for (int) maximum number of results list of aliases
stream_to_buffer <alias>

Dumps the whole content of the stream to the standard output. The entry must be a stream and must already exist. The stream is read in chunks from the database for maximum performance and reduced memory usage.

Param alias: (string) the alias of the entry, which must be a stream nothing if successful, an error message otherwise

Note

The stream may contain a lot of data.

stream_from_buffer <alias> <content>

Write the buffer to the stream. If an entry with an identical name already exists, it will be overwritten and not appended.

Param alias: (string) the alias of the entry, which must be a stream (string) the buffer to write to the stream nothing if successful, an error message otherwise
stream_to_file <alias> <path>

Dumps the whole content of the stream to the specified file. If the file already exists, it will be overwitten. The entry must be a stream and must already exist. The stream is read in chunks from the database for maximum performance and reduced memory usage.

Param alias: (string) the alias of the entry, which must be a stream (filepath) the path to the file to which the content of the stream will be dumped nothing if successful, an error message otherwise
stream_from_file <alias> <path>

Reads content from the specified file and writes it to the stream. If an entry with an identical name already exists, it will be overwritten and not appended. The file is read in chunks from disk for maximum performance and reduced memory usage.

Param alias: (string) the alias of the entry, which must be a stream (filepath) the path to the file whose content will be written into the stream nothing if successful, an error message otherwise
detach_tag <alias> <tag>

Remove a tag from the entry.

Param alias: (string) the alias of the entry (string) the tag to remove from the entry nothing if successful, an error message otherwise
detach_tags <alias> <tag> [ <tag> ... ]

Remove tags from the entry.

Param alias: (string) the alias of the entry (string) the tag to remove from the entry nothing if successful, an error message otherwise
version

Display the version information for the quasardb shell.