Safely Find Berkeley DB Logs to Archive with db5.3_archive

You will identify Berkeley DB log files that are no longer in use, record the database files needed for catastrophic recovery, and leave deletion until a backup has been checked. Allow about fifteen minutes for an existing environment, plus the time needed to copy it to your backup destination. The examples use Berkeley DB 5.3.28 from db5.3-util 5.3.28+dfsg2-7 on this machine. The unversioned db_archive command is the compatible alias from db-util 1:5.3.21ubuntu2.

You need read access to the Berkeley DB environment and enough space for a backup. The inspection commands are normally unprivileged. Use elevated privileges only when the environment is deliberately protected and your database operator procedure authorises that access. Do not point the command at a random directory as a test: opening an environment can create Berkeley DB state there.

1. Confirm the installed command

Check which binary will run, then print its library version. These commands only inspect the executable:

$ command -v db5.3_archive
/usr/bin/db5.3_archive
$ db5.3_archive -V
Berkeley DB 5.3.28: (September  9, 2013)

The same option works with db_archive. Prefer db5.3_archive in new scripts when you want the Berkeley DB major version to be obvious. Check the package version as well if you are diagnosing a distribution-specific issue:

$ 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

2. Select the real database home

Set a shell variable to the directory that contains the Berkeley DB environment. Replace the placeholder with the path used by your application:

$ DB_HOME='/srv/example-db'
$ test -d "$DB_HOME" && test -r "$DB_HOME" && echo 'database home is readable'
database home is readable

The -h option selects this home explicitly. Without it, the utility uses DB_HOME if that environment variable is set, or the current working directory. An explicit -h makes a scheduled job easier to review and avoids accidentally inspecting a different environment because its working directory changed.

Checkpoint: confirm the path before continuing. Do not create an empty directory merely to make the command produce output. The utility opens a Berkeley DB environment and may create or update log state as part of that operation.

3. List logs that are no longer in use

Run the default query against the selected environment:

$ db5.3_archive -h "$DB_HOME"
log.0000000042
log.0000000043

Each printed pathname is a log that Berkeley DB currently considers unused, and the default paths are relative to the database home. The actual names and count depend on active transactions, checkpoints and the environment's log history. An empty result is valid: it means there is no log currently reported as safe to archive. The command exits 0 on success and a value greater than 0 when an error occurs.

Use -a when the next tool needs absolute pathnames:

$ db5.3_archive -a -h "$DB_HOME"
/srv/example-db/log.0000000042
/srv/example-db/log.0000000043

Do not parse a human-formatted message as a filename. Capture standard output separately from standard error if a script will process the list:

$ db5.3_archive -a -h "$DB_HOME" > /tmp/example-db-archive-list
$ status=$?
$ printf 'archive query status: %s\n' "$status"
archive query status: 0

4. Record the files needed for recovery

The log list is not the complete backup set. Ask for database files that need to be archived to recover from catastrophic failure:

$ db5.3_archive -s -a -h "$DB_HOME"
/srv/example-db/accounts.db
/srv/example-db/orders.db

The result is environment-specific. A database file that has not been accessed during the current log lifetime may not appear, and a file already deleted from the system is ignored. Treat this output as an input to your backup procedure, not as permission to copy only the listed files without understanding your application's database layout. The manpage's recovery model requires both the relevant database files and the required logs.

Checkpoint: save the -s output with the backup record, then copy the database files and the unused logs to backup media. Verify the copy before considering any log removal. A successful cp or archive command proves that bytes were written, not that the backup is usable.

5. Review all logs when investigating space use

Use -l to list every database log file, including logs involved in active transactions:

$ db5.3_archive -l -a -h "$DB_HOME"
/srv/example-db/log.0000000040
/srv/example-db/log.0000000041
/srv/example-db/log.0000000042

This is an inventory, not a deletion recommendation. Logs shown by -l may still be needed by active work. If the command reports an environment error, stop and investigate the database service, permissions and path instead of deleting files to make space. Never remove or rename log files by hand while the application is running unless the Berkeley DB operator documentation for that application explicitly permits it.

6. Remove unused logs only after the backup checkpoint

After the backup checkpoint, run:

$ db5.3_archive -d -h "$DB_HOME"
$ printf 'removal status: %s\n' "$?"
removal status: 0

-d writes no filenames. Re-run the ordinary query to see what remains:

$ db5.3_archive -a -h "$DB_HOME"
$ printf 'remaining-query-status: %s\n' "$?"
remaining-query-status: 0

There is no undo option that recreates deleted log contents. Recovery is through the verified backup and its documented restore procedure. Keep the original backup and its file list until the retention policy says they can be discarded.

7. Handle shutdown and script failures

Give the utility a chance to detach cleanly from the environment. If you must stop a long-running invocation, send an interrupt signal rather than killing it abruptly:

$ kill -INT "$ARCHIVE_PID"

When automating the command, check its exit status and stop before copying or deleting anything if the query fails. Avoid passing an environment password with -P unless the database requires it and your local process-inspection policy accepts the short exposure of a command-line secret. Prefer the application's established secret-handling method where one exists.