Create a Safe Berkeley DB Hot Backup with db5.3_hotbackup

Stopping a busy database just to copy it is rarely an option, which is where db5.3_hotbackup earns its keep. You will take a recoverable snapshot of a Berkeley DB environment while its service is running, then check that the target holds the expected files. Allow 15 minutes for a first backup, plus the time to confirm the result with the application that owns the database.

This guide uses the installed Berkeley DB 5.3.28 utility, supplied by Ubuntu's db5.3-util package.

The command copies database files and log files into a separate directory, runs catastrophic recovery there, and removes logs that recovery no longer needs. It does not make a prepared transaction ready for failover, and it can remove files from an existing target. Read the warnings before copying a command.

1. Identify the utility and source environment

Run the checks as the account that owns the Berkeley DB environment, unless your service's permissions require a carefully scoped elevated command. Do not start with sudo: root-owned backup files can make later maintenance harder.

$ command -v db5.3_hotbackup
/usr/bin/db5.3_hotbackup
$ db5.3_hotbackup -V
Berkeley DB 5.3.28: (September  9, 2013)
$ test -d /srv/example-db && echo source directory exists

Replace /srv/example-db with the actual Berkeley DB environment home. The -h option names this directory. If you omit it, the program can use DB_HOME, or an environment discovered from the current directory. Use -h in a script so the source is visible during review.

Checkpoint: write down the source path and the account that normally opens it. The backup target must be a different filesystem path, and should be protected from the service account if the backup is meant to survive a compromise of that service.

2. Inspect DB_CONFIG before choosing copy options

Look for DB_CONFIG in the source home. It may place data or logs in directories outside the home directory:

$ if test -f /srv/example-db/DB_CONFIG; then
>   sed -n '1,160p' /srv/example-db/DB_CONFIG
> else
>   echo 'No DB_CONFIG in the source home'
> fi

Without -D, the utility searches the home directory for application files and log files, unless you provide one or more -d data directories and a separate -l log directory. Use -D when the DB_CONFIG data-directory layout is part of the environment you need to reproduce. It copies the configuration and its data directories into the target.

Warning: do not use -D with absolute data-directory or log-directory paths. The copied configuration would still point at the source locations, so recovery in the target could write into the live environment. Relative paths containing .. also need a deliberate review: the target names must be distinct and meaningful.

3. Prepare an empty, dedicated target

Choose a target that is not the source and that contains no files you need to keep. When the target already exists, a normal run removes all files in it before copying. When it does not exist, it is created with owner read, write and execute permissions.

$ install -d -m 700 /srv/example-db-hot-2026-09-22
$ find /srv/example-db-hot-2026-09-22 -mindepth 1 -maxdepth 1 -print
$ test "$(realpath /srv/example-db)" != "$(realpath /srv/example-db-hot-2026-09-22)" && echo paths are distinct

Destructive action: do not run the backup command until the target listing is empty or every listed file is disposable. The utility has no undo for files it removes from that directory. If you need to keep an older snapshot, choose a new target or move the old snapshot using your normal retention process.

4. Create the hot backup

This example includes -D because the preceding inspection established that the environment uses safe, relative DB_CONFIG data directories. Leave it out when that does not apply. The -v output makes the copy and recovery stages easier to audit.

$ db5.3_hotbackup -v -D \
>   -h /srv/example-db \
>   -b /srv/example-db-hot-2026-09-22
$ status=$?
$ printf 'backup exit status: %s\n' "$status"
backup exit status: 0

-d DIRECTORY: give it once for each separate source data directory when you are not using -D.
-l DIRECTORY: use it when logs are stored separately.
Filename clashes: if the same filename is present in multiple -d directories, later copies can overwrite earlier ones, because the target is a single backup location. Plan distinct names or use the DB_CONFIG layout.

Warning: if the source uses encrypted Berkeley DB data, -P PASSWORD supplies the environment password. Avoid putting passwords on a command line where other users can inspect process arguments. Prefer the application's established secret-handling method; the manpage warns that the utility cannot eliminate every exposure window.

5. Verify the snapshot without opening it as production

First confirm that the command returned zero and that the target is not empty. The exact filenames depend on the application:

$ test -s /srv/example-db-hot-2026-09-22/__db.001 && echo shared memory file present
$ find /srv/example-db-hot-2026-09-22 -maxdepth 2 -type f -printf '%P\n' | sort
$ du -sh /srv/example-db /srv/example-db-hot-2026-09-22

Do not assume __db.001 exists for every environment, and do not treat matching byte totals as proof of a usable backup. The useful checks are that the expected application files, logs and any copied DB_CONFIG paths are present.

Then test the target with the application's documented read-only or restore procedure on an isolated host. Do not point the live service at it just to see whether it opens.

6. Update an existing snapshot with new logs

For a pre-existing hot backup, -u removes old log files in the target and copies new logs. It does not copy databases. Use it only when the target is already a valid base snapshot and you understand the source and target relationship:

$ db5.3_hotbackup -v -u \
>   -h /srv/example-db \
>   -b /srv/example-db-hot-2026-09-22
$ test "$?" -eq 0 && echo snapshot logs updated

If the base snapshot is missing or suspect, create a fresh target instead.

Warning: a failed update can leave the target unsuitable for failover. Keep an independently verified snapshot until the replacement has passed your restore test.

7. Handle service interruption and prepared transactions

The utility attaches to the Berkeley DB environment while it works. If you interrupt it, send SIGINT and let it detach and exit cleanly. Do not kill it repeatedly or remove files from the source while it is running.

Applications using DB_TXN->prepare can leave transactions in the prepared state. This utility does not resolve them.

During a real failover, the application must open the environment with DB_RECOVER_FATAL and use DB_ENV->txn_recover to resolve pending work. Ask the application owner to document that procedure before treating this snapshot as a failover plan.

Done means

Utility confirmed. The installed command is Berkeley DB 5.3.28 and the source path is explicit.
Target clean. It is separate, dedicated and empty before a fresh backup.
Config reviewed. DB_CONFIG paths were checked, and -D was used only with safe relative paths.
Backup checked. The command returned exit status 0 and the target contains the expected files and logs.
Restore tested. A separate restore test has opened or inspected the snapshot safely.
Failover covered. The failover procedure handles prepared transactions rather than assuming the snapshot resolves them.