2.4. quasardb database tool

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

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.