# 1.4. quasardb database tool¶

## 1.4.1. Introduction¶

The quasardb database tool enables you to analyze, dump, repair, upgrade, backup, restore, and verify backups of your quasardb node.

Warning

Improper usage of this program can irreversibly damage your database. Do not use this tool lightly. Contact your QuasarDB Solution Architect if you have any doubt.

## 1.4.2. Quick Reference¶

Option

Usage

display help

display qdb_dbtool version

--database

path to the database

analyzes the database

repairs the database

--upgrade

performs a database backup

--restore

restores a database backup

--compact

compacts the database

--scan

scans for errors

--verify_backup

verifies database backups

## 1.4.3. Important notice¶

DBTool requires exclusive access to the database files. The daemon cannot run at the same time.

In all our example, we will assume a database stored in /var/db/qdb

## 1.4.4. Log level¶

You can control the verbosity of the output with the log-level switch.

The supported levels are:

• Panic (least verbose)

• Error

• Warning

• Info (default)

• Debug

• Detailed (most verbose)

For example, this is an analysis lauched with the maximum verbosity:

qdb_dbtool --database=/var/db/qdb --analyze --log-level=detailed


## 1.4.5. Analyzing¶

DBTool can analyze the database:

qdb_dbtool --database=/var/db/qdb --analyze


It will then tell you:

• When the database was last opened and closed

• The number of entries

• An approximate disk usage

## 1.4.6. Scanning¶

DBTool can scan for errors in a database:

qdb_dbtool --database=/var/db/qdb --scan


Warning

Scanning is an I/O intensive operation and can take a very long time for large databases.

You can use multiple threads to speed up scanning, for example, to use 4 threads:

qdb_dbtool --database=/var/db/qdb --jobs=4 --scan


By default, scanning will only look for each bucket’s latest version (QuasarDB uses MVCC internally).

You can ask to scan all the versions:

qdb_dbtool --database=/var/db/qdb --scan --all-versions


If errors are found, it means your data has been corrupted, and you may need to delete shards or restore the data manually. Please contact your QuasarDB Solutions Architect if you find yourself in such a situation. We may be able to salvage some of your data.

You should upgrade your database between every branch change. For example, if you move from QuasarDB 3.8 to QuasarDB 3.9, you should upgrade the database. This is because, between version, we may change how internal structures, especially indexes, are encoded.

Failure to do so may result in degraded performance, or worse, a malfunctioning database.

Note

The QuasarDB daemon will not upgrade the database. You must use DBTool to upgrade the database.

The process is the following:

• Turn off the daemon

• Turn on the daemon

• Do this on every node

qdb_dbtool --database=/var/db/qdb --upgrade


You can force complete index reconstruction:

qdb_dbtool --database=/var/db/qdb --upgrade --force


A complete index reconstruction is slower, but guarantees that all indexes use the latest implementation.

## 1.4.8. Offline compaction¶

You can compact the LSM tree offline with DBTool. This may be needed, for example, if you wish to manually copy or move the files to a different disk and want to ensure the database is as small as possible. You can also compact the files explicitly online with the cluster_trim_all shell command.

To compact the database offline:

qdb_dbtool --database=/var/db/qdb --compact


Note

Compacting the database is an I/O intensive operation.

## 1.4.9. Backup and restore¶

DBTool offers incremental backup and restore (the last 32 versions are kept). This may be more efficient than manually copying the files.

To backup the database to /var/db/qdb_backup:

qdb_dbtool --database=/var/db/qdb --backup=/var/db/qdb_backup


You can then verify your backup:

qdb_dbtool --database=/var/db/qdb --verify-backup=/var/db/qdb_backup


It will tell you the backup’s size, when it was made, its size, and perform integrity validation.

To restore a backup:

qdb_dbtool --database=/var/db/qdb --restore=/var/db/qdb_backup


Note

Restoring a backup will overwrite the existing database.

--database=<path>

Specifies the directory where data is persisted when using the RocksDB storage engine for the node where the process has been launched.

Argument

A string representing a full path to the directory where data is persisted.

-a, --analyze

Run a key/value store analysis.

-r, --repair

Best effort repair on key/value store.

--upgrade

Best effort upgrade of the persistence layer.

-b, --backup

Performs an incremental backup of the database.

--restore

Restores a database backup.

--compact

Compacts the database.

--scan

Scan for errors.

--verify_backup

Verifies database backups.