Verify a Berkeley DB 5.3 File Without Taking It Offline

You will check the structure of a Berkeley DB file with db5.3_verify, confirm whether the command succeeded, and avoid the locking mistake that can make a live database less safe. Allow about ten minutes for a single file, plus more time if you need to identify the process that owns it.

This guide matches Berkeley DB 5.3.28, provided here by db5.3-util version 5.3.28+dfsg2-7. The package also provides the db_verify alias through db-util version 1:5.3.21ubuntu2. Check your own package versions before relying on details in an automated check.

1. Check the installed utility

Start with read-only checks. No elevated privileges are needed unless the database or its directory is not readable by your account:

$ command -v db5.3_verify
/usr/bin/db5.3_verify
$ db5.3_verify -V
Berkeley DB 5.3.28: (September  9, 2013)
$ dpkg-query -W -f='${Package} ${Version}\n' db5.3-util db-util
db-util 1:5.3.21ubuntu2
db5.3-util 5.3.28+dfsg2-7

The version output is the Berkeley DB library version, not a verification result. The equivalent command name db_verify accepts the same options on this installation, but using the versioned name makes a script's dependency clearer.

2. Stop writers before you verify

Do not point this utility at a database that another process may be modifying. The manpage explicitly says that db5.3_verify performs no locking, including when the database environment has a locking subsystem. A concurrent write can therefore produce an inconsistent check and, in an environment, risks corruption.

Before running the check, pause the application or take the database out of service using its normal operational procedure. That may require an administrator, but the verification command itself is normally unprivileged. If you cannot establish a quiet window, do not treat a failed verification as proof that the file is damaged.

Checkpoint: identify the exact file and preserve the original. Verification reads the file, but copying, moving or repairing it would be a separate state-changing operation.

3. Verify a standalone database file

Pass one or more database file names after the options. This example checks a file in a directory you own:

$ db5.3_verify /srv/app/data/accounts.db
BDB5105 Verification of /srv/app/data/accounts.db succeeded.
$ printf 'exit status: %s\n' "$?"
exit status: 0

Exit status 0 means the utility completed successfully. Berkeley DB may still print informational text such as the BDB5105 line. Do not write a script that parses that sentence when the numeric status is available.

Several files can be checked in one invocation:

$ db5.3_verify /srv/app/data/accounts.db /srv/app/data/sessions.db
$ printf 'exit status: %s\n' "$?"
exit status: 0

The command exits with a value greater than zero when an error occurs. For example, a missing path produces an error and a non-zero status:

$ db5.3_verify /srv/app/data/missing.db
db5.3_verify: /srv/app/data/missing.db: No such file or directory
BDB5105 Verification of /srv/app/data/missing.db failed.
$ printf 'exit status: %s\n' "$?"
exit status: 1

4. Account for the database environment

A Berkeley DB file can belong to an environment rather than being an isolated file. Use -h to name the environment home explicitly:

$ db5.3_verify -h /srv/app/db-env /srv/app/data/accounts.db

If -h is absent and DB_HOME is set, the utility uses that environment path. Otherwise its default home is the current working directory. This default is easy to miss when a command is launched from a service unit, cron job or a different shell directory, so prefer an explicit -h when the file depends on an environment.

The environment must also be quiet. If the process needs time to detach from an environment, the manpage says to send it an interrupt signal, SIGINT, so it can release resources and exit cleanly. Do not kill a verification process with an arbitrary signal while it is attached to a live environment.

5. Handle custom ordering

By default, the utility checks B-tree and duplicate sort order as well as hash ordering. A database created with non-default comparison or hashing functions can therefore fail a command-line verification even when the stored pages are usable.

For that case, retry with -o:

$ db5.3_verify -o /srv/app/data/custom-order.db
$ printf 'exit status: %s\n' "$?"
exit status: 0

This skips those ordering checks. It is not a full verification of the custom database. The manpage says full checking requires the Berkeley DB DB->verify method after the correct comparison or hashing functions have been configured. Do not use -o merely to hide an unexplained failure.

6. Keep diagnostic options narrow

Use -q only when a caller needs success or failure without error descriptions:

$ db5.3_verify -q /srv/app/data/accounts.db
$ printf 'exit status: %s\n' "$?"
exit status: 0

-N prevents acquisition of shared-region mutexes and can ignore other potentially fatal Berkeley DB problems. The manpage reserves it for debugging errors. Do not add it to routine monitoring or recovery scripts.

Avoid putting passwords on the command line. The -P option accepts an environment password, but command-line arguments can be visible to other users for a short time. Use the application's safer credential mechanism where one exists, and treat any command containing -P as security-sensitive.