The quasardb shell is a command line tool that enables you to add, update, delete and retrieve entries from a quasardb server or cluster. The shell can be used interactively and non-interactively. In interactive mode, the user enters commands to be executed on the server. 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 to a qdbd running on the same machine, listening on the port 2836. If this is not the case - for example if your daemon runs on 192.168.1.1 and listens on the port 303 - you will need to set the –daemon parameter as shown below:
qdbsh --daemon=192.168.1.1:303
When connecting to a cluster, any server within the cluster is capable of servicing requests. There is no “master” or “preferred” server. There is no performance impact of choosing one server instead of the other, except, perhaps, the physical capabilities of the server.
Command Usage cas alias content comparand atomically compares and swaps the entry exit exit the shell (interactive mode only) expires_at alias expiry sets the absolute expiry time of the entry expires_from_now alias delta sets the entry expiry time to seconds relative to now. get returns the entry content get_expiry returns the entry’s aboslute expiry time get_update alias atomically get and update the entry help display help node_config host returns the node configuration as a JSON string node_status host returns the node status as a JSON string node_topology host returns the node topology as a JSON string prefix_get prefix returns the list of aliases matching the given prefix put put data, fails if entry already exists remove alias removes the entry remove_all removes ALL entries on the WHOLE cluster (Dangerous!) remove_if alias data removes the entry in case of match stop_node host reason stops the node update alias data updates the entry. The entry will be created if it doesn’t exist version display quasardb version
The interactive mode enables the user to enter as many commands as needed. The shell will provide the user with feedback upon success and failure. If needed, it will display the content of retrieved entries.
As soon as qdbsh is properly initialized, the following prompt is displayed:
qdbsh:ok >
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. Keep in mind though, that binary content may not be correctly printed and may even corrupt your terminal display.
When the last command has been successfully executed, the prompt will show:
qdbsh:ok >
In case of error, the prompt turns into:
qdbsh:ko >
Non-interactive mode enables the user 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 server every time the shell is run.
The command to be executed is supplied as a parameter to the shell. For the list of supported commands, see Commands.
As it is in interactive mode, the server and port is specified with the --daemon parameter. Only one command may be specified per run.
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.
Unless otherwise specified, qdbsh assumes the server is running on localhost and on the port 2836.
Save the content of an entry named “biography” in a text file named “biography.txt”:
qdbsh get biography > biography.txt
Compress a file named “myfile”, then add its content to an entry named “myfile” on the quasardb server at 192.168.1.1:
bzip2 -c myfile | qdbsh --server=192.168.1.1 put myfile
Parameters can be supplied in any order and are prefixed with --. The arguments format is parameter dependent. Any parameter not in this list will be parsed by qdbsh as a quasardb command. See Interactive mode for more information.
Displays basic usage information.
To display the online help, type:
qdbsh --help
Specifies the address and port of the quasardb daemon on which the shell will connect. Either a DNS name, an IPv4 or an IPv6 address.
If the daemon is on localhost and listens on port 3001:
qdbsh --daemon=localhost:3001
A command generally requires one or several arguments. Each argument is separated by one or several space characters.
Atomically compares the value of an existing entry with comparand and replaces it with content in case of match. The entry must already exist.
| Param alias: | (string) the alias of the entry to get and update. |
|---|---|
| Param content: | (string) the new content of the entry. |
| Param comparand: | |
| (string) the value to compare the content to | |
| Return: | (string) the entry’s original content or an error message |
Note
The alias cannot contain the space character and its length must be below 1024. The new content can only be printable characters. This is a qdbsh restriction only. There must be one space and only one space between the comparand and the content. There is no practical limit to the comparand length and all characters until the end of the input will be used for the comparand, including space characters.
Exits the shell.
Sets the expiry time of an existing entry from the quasardb cluster.
| Param alias: | A string representing the entry’s alias for which the expiry must be set. |
|---|---|
| Param expiry: | The absolute time at which the entry expires. |
Sets the expiry time of an existing entry from the quasardb cluster.
| Param alias: | A string representing the entry’s alias for which the expiry must be set. |
|---|---|
| Param delta: | A time, relative to the call time, after which the entry expires. |
Retrieves an existing entry from the server and print it to standard output.
| Param alias: | (string) the alias of the entry to be retrieved. |
|---|---|
| Return: | (string) the entry’s content or an error message |
Retrives an entry whose alias is “alias” and whose content is the string “content”:
qdbsh:ok > get alias
content
qdbsh:ok >
Note
The entry alias may not contain the space character. The alias may not be longer than 1024 characters.
Retrieves the expiry time of an existing entry.
| Param alias: | (string) the alias of the entry |
|---|---|
| Return: | (string) the expiry time of the alias |
Atomically gets the previous value of an existing entry and replace it with the specified content. The entry must already exist.
| Param alias: | (string) the alias of the entry to get and update. |
|---|---|
| Param content: | (string) the new content of the entry. |
| Return: | (string) the entry’s content or an error message |
Adds an entry whose alias is “myentry”, and whose content is the string “MagicValue”:
put myentry MagicValue
Update the content to “VeryMagicValue” and gets the previous content:
get_update myentry MagicValue
VeryMagicValue
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.
Displays basic usage information and lists all available commands.
Returns 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. |
Returns 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. |
Returns 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. |
Returns the list of aliases matching the given prefix.
| Param prefix: | (string) A prefix to search for. |
|---|---|
| Return: | (string) The list of matching aliases. |
Adds a new entry to the server. The entry must not already exist. Keys beginning with the string “qdb” are reserved and cannot be added to the cluster.
| Param alias: | (string) the alias of the entry to create |
|---|---|
| Param content: | (string) the content of the entry |
| Return: | nothing if successful, an error message otherwise |
Adds an entry whose alias is “myentry” and whose content is the string “MagicValue”:
put myentry MagicValue
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.
Removes an existing entry on the server. It is an error to delete a non-existing entry.
| Param alias: | (string) the alias of the entry to delete |
|---|---|
| Return: | Nothing if successful, an error message otherwise |
Removes an entry named “obsolete”:
remove obsolete
Removes all entries from the server. This command is not atomic.
| 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.
Atomically compares the entry with the comparand and removes it if, and only if, they match.
| Param alias: | The entry’s alias to delete. |
|---|---|
| Param comparand: | |
| The entry’s content to be compared to. | |
| Returns: | True if the entry was successfully removed, false otherwise. |
Stops the node designated by its host and port number. This stop is generally effective within a few seconds of being issued, enabling inflight calls to complete successfully.
| Param host: | (string) The node designated by its host and port number (e.g. “127.0.0.1:2836”) |
|---|
Adds or updates an entry to the server. If the entry doesn’t exist it will be created, otherwise it will be changed to the new specified value.
| Param alias: | (string) the alias of the entry to create or update. |
|---|---|
| Param content: | (string) the content of the entry. |
| Return: | Nothing if successful, an error message otherwise. |
Adds an entry whose alias is “myentry” and whose content is the string “MagicValue”:
update myentry MagicValue
Change the value of the entry “myentry” to the content “MagicValue2”:
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.
Displays version information.