2.1. quasardb shell#

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

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

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

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

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

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

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

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

2.1.5.2. Administrative#

Command	Arguments	Description
`cluster_compact`	`[full\|piecewise] [timeout]`	compact the data in the persistence layer on the whole cluster. ‘full’ compacts all the data in a single operation, whereas ‘piecewise’ splits the data into multiple chunks and then compacts each separately. ‘full’ is faster, but requires more memory, cpu, and disk I/O
`cluster_disable_auto_compaction`		disables the persistence automatic compaction on the cluster
`cluster_enable_auto_compaction`		enables the persistence automatic compaction on the cluster
`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`	`cluster_uri timeout_in_seconds`	print status information about a cluster
`cluster_export_raw_table`	`alias directory [max_batch_bytes] [true\|false]`	Export the internal records of a time-series table. The last argument specifies whether to ignore corrupted keys.
`cluster_import_raw_table`	`manifest_file [true\|false]`	Import internal table records. The optional argument specifies whether to replace an existing table.
`cluster_export_symbol_tables`	`alias symbols_file`	Export the symbol tables that a time-series table uses.
`cluster_import_symbol_tables`	`symbols_file [true\|false]`	Import symbol tables. The optional argument specifies whether to skip symbol tables that already exist.
`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

2.1.5.2.1. Raw table migration#

QuasarDB 3.14.3 and later can export and import the internal records of a time-series table. Use this function to move a table between compatible clusters. This format is not CSV, TSV, or Parquet. To exchange table data with other systems, use COPY (export) and IMPORT.

2.1.5.2.1.1. Export a raw table#

Use this command on the source cluster:

cluster_export_raw_table trades C:/qdb-transfer/trades

The command creates one or more .qdbraw part files and a JSON manifest. It returns the path of the manifest. Keep the manifest and all part files in the same directory.

The optional max_batch_bytes argument sets the maximum size of an export batch. A value of 0 uses the default size. The final true|false argument controls corrupted-key handling. The default is false. If you set it to true, the export ignores corrupted keys.

2.1.5.2.1.2. Import a raw table#

Give the manifest path to the command on the destination cluster:

cluster_import_raw_table C:/qdb-transfer/trades/trades-20260807T180000Z.manifest.json

Before the import starts, QuasarDB checks the size and checksum of each part file. The import stops if a part is missing or invalid.

By default, the command returns an error if the table exists. Set the optional argument to true to remove the existing table before the import:

Warning

The following command deletes the existing table before it imports the raw records. You cannot undo this operation.

cluster_import_raw_table C:/qdb-transfer/trades/trades-20260807T180000Z.manifest.json true

2.1.5.2.1.3. Move symbol tables#

If the table has SYMBOL columns, move its symbol tables before you import the raw table. First, export the symbol tables from the source cluster:

cluster_export_symbol_tables trades C:/qdb-transfer/trades-symbols.json

Then, import the file into the destination cluster:

cluster_import_symbol_tables C:/qdb-transfer/trades-symbols.json

By default, the import returns an error if a symbol table exists. Add true to skip existing symbol tables:

cluster_import_symbol_tables C:/qdb-transfer/trades-symbols.json true

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

2.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
`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

2.1.5.5. Direct node interface#

Direct node communication is a collection of APIs that works on the specified node only. Each node has a local storage that can only be acceded through the direct node API. Statistics are, for example, stored in this local storage.

Command	Arguments	Description
`direct_set_node`	`uri`	set the node to connect to directly - by default th
`direct_get_node`	None	return the URI of the node currently connected to
`direct_blob_get`	`alias`	return the blob value of the provided alias in the local key/value store of the node
`direct_int_get`	`alias`	return the integer value of the provided alias in the local key/value store of the node
`direct_prefix_get`	`prefix max_count`	return all keys matching the given prefix, up to the specified limit count
`direct_backup`	`path flags max_increments`	triggers a node backup in the specified directory (accessible from the node)

-h, --help#: Display help.

-v, --version#: Display quasardb version.

-c#: Run a quasardb command.

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