Find Safe-to-Archive Berkeley DB Logs with db5.3_archive

Delete the wrong Berkeley DB log file and catastrophic recovery stops being possible, so db5.3_archive tells you which logs are safe first. You will list unused logs, record the database files needed for recovery, and leave deletion until a backup has been checked. Allow about fifteen minutes, plus the time to copy the environment 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.

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 your application uses:

$ 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. It also stops the job inspecting a different environment because its working directory changed.

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 pathname is an unused log. Berkeley DB currently considers it unused, and the default paths are relative to the database home.
• Names and count vary. They depend on active transactions, checkpoints and the environment's log history.
• An empty result is valid. It means no log is currently reported as safe to archive.
• Exit status. The command exits 0 on success and 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 the database files that need archiving 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.

5. Review all logs when investigating space

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. Do not delete files to make space.

6. Remove unused logs 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

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.