2.4. quasardb database tool#

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

2.4.2. Quick Reference#

Option

Usage

-h, --help

display help

-v, --version

display qdb_dbtool version

--database

path to the database

-a, --analyze

analyzes the database

-r, --repair

repairs the database

--upgrade

upgrades the database

-b, --backup

performs a database backup

--restore

restores a database backup

--compact

compacts the database

--scan

scans for errors

--verify_backup

verifies database backups

Option	Usage
`-h`, `--help`	display help
`-v`, `--version`	display qdb_dbtool version
`--database`	path to the database
`-a`, `--analyze`	analyzes the database
`-r`, `--repair`	repairs the database
`--upgrade`	upgrades the database
`-b`, `--backup`	performs a database backup
`--restore`	restores a database backup
`--compact`	compacts the database
`--scan`	scans for errors
`--verify_backup`	verifies database backups

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

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

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

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

2.4.7. Upgrading#

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

Run DBTool on your directory with the upgrade switch

Turn on the daemon

Do this on every node

Upgrading the database:

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.

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

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