# 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

display help

display quasardb version

-c

run a qdb command

list available commands

--cluster

cluster URI

qdb://127.0.0.1:2836

--color-output

color output mode

automatic

--user-security-file

path to the file containing the user’s security token 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

return the metainformation about the entry

get_type alias

return the type of the entry

remove alias

remove the entry from the cluster

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 … ]

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

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-security-file <filepath>

Specifies a path to the file containing the user’s security token 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

Return

tabular result of the query

find <query>

Run a find query on the database.

Param query

(string) query

Return

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

(string) the alias of the Blob

Param content

(string) the new content of the Blob

Param comparand

(string) the value to compare against content

Return

(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

Return

(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

Param content

(string) the new content of the Blob

Return

(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

Param content

(string) the content of the Blob

Return

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

(string) The alias of the Blob

Param comparand

(string) The value to compare against the content of the Blob

Returns

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

(string) The pattern to be searched for, byte-wise

Param max_count

(int) maximum number of results

Returns

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

(string) The regular expression to be searched for

Param max_count

(int) maximum number of results

Returns

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

Param content

(string) the content of the Blob

Return

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

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

Param expiry

(string) The absolute time at which the entry expires

Return

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

Param delta

(string) A time, relative to the call time, after which the entry expires

Return

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

Return

(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

Return

(string) the metadata of the entry

get_type <alias>

Retrieve the type of an existing entry.

Param alias

(string) the alias of the entry

Return

(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

Return

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

Param value

(int) the value to add to the Integer

Return

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

Return

(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

Param value

(int) the value of the Integer

Return

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

Param content

(int) the content of the Integer

Return

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”)

Return

(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”)

Return

(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”)

Return

(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

Return

(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

Return

(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

Return

(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

Return

(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

Param content

(string) the value to add to the end of the Deque

Return

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

Param content

(string) the value to add to the start of the Deque

Return

nothing if successful, an error message otherwise

deque_size <alias>

Return the size of the Deque.

Param alias

(string) the alias of the Deque

Return

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

Param tag

(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

Param tag

(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

Return

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

Return

approximative number of tagged entries

get_tags <alias>

Get a list of tags for the specified entry.

Param alias

(string) the entry to check

Return

list of aliases

has_tag <alias> <tag>

Determine if an entry has a specified tag.

Param alias

(string) the alias of the entry

Param tag

(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

(string) prefix to search for

Param max_count

(int) maximum number of results

Return

list of aliases

suffix_get <suffix> <max_count>

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

Param suffix

(string) suffix to search for

Param max_count

(int) maximum number of results

Return

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

Return

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

Param content

(string) the buffer to write to the stream

Return

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

Param path

(filepath) the path to the file to which the content of the stream will be dumped

Return

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

Param path

(filepath) the path to the file whose content will be written into the stream

Return

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

Param tag

(string) the tag to remove from the entry

Return

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

Param tag

(string) the tag to remove from the entry

Return

nothing if successful, an error message otherwise

version

Display the version information for the quasardb shell.