1.1. quasardb shell

1.1.1. Introduction

The quasardb shell is a command line tool that enables you to interact with 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 default port 2836 - you will need to pass the address and port as a qdb:// URI string, shown below:

$ qdbsh qdb://192.168.1.1:2836

If you wish to connect to a secure cluster, you can use the following command:

$ qdbsh --cluster qdb://192.168.1.1:2836 \
        --cluster-public-key-file /usr/share/qdb/cluster_public.key \
        --user-security-file /path/to/my/security.key

You will need to replace the locations of the cluster public key file /usr/share/qdb/cluster_public.key and your user security file /path/to/my/security.key with those provided by your system administration. Please refer to our security documentation for more information.

1.1.2. 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-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

1.1.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 Command reference.

If you are looking for an example usage, please refer to the QuasarDB primer which uses an interactive qdbsh session to guide you through the first steps.

1.1.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 Command reference.

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.

1.1.4.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

1.1.5. Command reference

If you want to use qdbsh in conjunction with our SQL query language, you can just use them directly from the QuasarDB shell.

In addition to these timeseries-oriented commands, qdbsh also supports the key/value API and more administrative commands which are described below.

1.1.5.1. General

Command

Arguments

Description

help

Display help page

exit

Exit the shell

version

display version information of qdbsh and the quasardb daemon

1.1.5.2. Administrative

Command

Arguments

Description

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

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

1.1.5.3. Tags

Command

Arguments

Description

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 approximate 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

1.1.5.4. Key/Value

Command

Arguments

Description

find

find key/value entries that match certain parameters

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

remove

alias

remove the entry from the cluster

get_metadata

alias

return the metainformation about the entry

get_type

alias

return the type of the entry

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

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

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

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

-l, --list-commands

List available commands.

--cluster

Cluster URI

Argument

A string representing the URI of the cluster to connect to.

Default value

qdb://127.0.0.1:2836

--color-output

Color output mode.

Default value

automatic

--user-security-file

path to the file containing the user’s security token used for connection

Argument

A string representing the path to the file containing the user’s security token.

--cluster-public-key-file

path to the file containing the public key of the cluster to connect to

Argument

A string representing the path to the file containing the public key of the cluster.