Table Of Contents

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

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_update alias content update an existing Blob or creates a new Blob
cluster_purge remove ALL entries on the WHOLE cluster (dangerous!)
cluster_trim remove unused versions of entries from the cluster
cluster_status 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
attach_tag alias tag add a tag to an entry
detach_tag alias tag removes a tag from an entry
get_tagged tag get entries with the given tag
has_tag alias tag returns true if the entry has the tag
stream_to_buffer alias dumps the content of a stream
stream_from_buffer alias content write content into a stream
stream_to_file alias file_path dumps the content of a stream into a file
stream_from_file alias file_path loads a file and adds it into a file
version display the quasardb version

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 print 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"

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

Run a select query on the database.

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

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_trim

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

Return:nothing if successful, an error message otherwise
cluster_status

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.
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_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:(string) 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:(string) 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:(string) 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:(string) 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) The 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) The 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.
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
get_tagged <tag>

Get a list of entries tagged with the specified tag.

Param tag:(string) the tag to search for
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
stream_to_buffer <alias>

Dumps the whole content of the stream to the standard output. Warning, the stream may contain a lot of data. 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.
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:(string) 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:(string) 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.
version

Display the version information for the quasardb shell.

arrow_backPrevious
5.3. quasardb user adder
Next arrow_forward
5.5. quasardb web server