2.4. quasardb database tool#
The quasardb database tool enables you to analyze, dump, repair, upgrade, backup, restore, and verify backups of your quasardb node.
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#
display qdb_dbtool version
path to the database
analyzes the database
repairs the database
upgrades the database
performs a database backup
restores a database backup
compacts the database
scans for errors
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
2.4.4. Log level#
You can control the verbosity of the output with the
The supported levels are:
Panic (least verbose)
Detailed (most verbose)
For example, this is an analysis lauched with the maximum verbosity:
qdb_dbtool --database=/var/db/qdb --analyze --log-level=detailed
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
DBTool can scan for errors in a database:
qdb_dbtool --database=/var/db/qdb --scan
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.
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
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
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
Restoring a backup will overwrite the existing database.
Specifies the directory where data is persisted when using the RocksDB storage engine for the node where the process has been launched.
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.
Best effort upgrade of the persistence layer.
- -b, --backup#
Performs an incremental backup of the database.
Restores a database backup.
Compacts the database.
Scan for errors.
Verifies database backups.