Recover a Berkeley DB 5.3 Environment Safely After a Crash

You will restore a Berkeley DB environment to a consistent state after an unexpected application, database or system failure. The installed command is Berkeley DB 5.3.28, from Debian package db5.3-util version 5.3.28+dfsg2-7; the db_recover command is a symlink to the same binary. Allow about fifteen minutes for a straightforward recovery, plus time to locate a trustworthy backup if the failure was catastrophic.

Recovery changes the environment. Stop the application that owns it first, and make sure nobody else is opening the same environment. Committed transactions should be present after recovery; uncommitted transactions are undone. Do not treat this command as a general database repair tool or run it against a guessed directory.

1. Confirm the installed command and owner

These checks are ordinary, read-only commands and normally need no elevated privileges:

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

Use db5.3_recover in scripts so the Berkeley DB version is explicit. The alias is useful when documentation or an older deployment names the utility db_recover. The local package also accepts an -f option in its usage output, but the installed manpage documents the recovery controls covered here, so do not add undocumented flags to a production command.

Find the environment path from the application configuration, service unit or operator notes. A directory containing unrelated files is not a safe substitute. The utility uses the current directory by default, the path passed to -h, or DB_HOME when -h is absent.

2. Stop the writer and record a checkpoint

Stop the application or service that writes the environment, using its normal service procedure. This is the point where service disruption begins. Run the recovery as the account that owns the Berkeley DB files. Use sudo only when that account or directory permissions require it; changing ownership or running the utility as root can leave an environment the application cannot reopen.

Write down the exact environment directory and confirm that it is the intended one:

$ DB_HOME='/srv/berkeley/example-env'
$ test -d "$DB_HOME" && printf '%s\n' "Environment: $DB_HOME"
Environment: /srv/berkeley/example-env
$ find "$DB_HOME" -maxdepth 1 -type f -printf '%f\n' | sort

The file list is only an inspection aid. Do not delete logs, rename database files or run a cleanup job before recovery. Missing log files can make recovery fail, and the missing files must then be restored before trying again.

3. Run normal recovery

For an ordinary crash where the environment files and their log files are still present, run normal recovery with -h:

$ db5.3_recover -h "$DB_HOME"
$ status=$?
$ printf 'db5.3_recover exit status: %s\n' "$status"
db5.3_recover exit status: 0

A successful run normally has no progress report to parse. The exit status is the useful result: 0 means success, while a value greater than zero means an error. Recovery makes committed transactions available and completely rolls back uncommitted transactions. It is therefore normal for the post-recovery state not to contain work that was still in progress when the failure occurred.

Do not omit -h merely because you changed directory earlier. An explicit path makes the command reviewable and prevents recovery from operating on whichever directory a shell, cron job or service wrapper happens to use.

4. Handle a missing-log failure

If the command reports that one or more log files are missing, stop. Do not create empty replacement files and do not rerun recovery repeatedly. Restore the named logs from the matching backup or storage snapshot, keep them in the location expected by the environment, and run the same command again.

After restoring the logs, capture the status again:

$ db5.3_recover -h "$DB_HOME"
$ status=$?
$ test "$status" -eq 0
$ printf 'Recovery completed for %s\n' "$DB_HOME"
Recovery completed for /srv/berkeley/example-env

The test command prints nothing when recovery succeeds. If it fails, the shell continues to the next line unless you use a stricter wrapper, so inspect $status before starting the application. A failed recovery is not a repaired environment.

5. Use catastrophic recovery only with a matching snapshot

Use -c only when the database files have been restored from an archival snapshot and you also have every log file written since that snapshot was made. This is a destructive, service-disrupting operation: it reconstructs from the snapshot and log history rather than treating the current files as a complete post-failure environment.

$ db5.3_recover -c -h "$DB_HOME"
$ status=$?
$ printf 'Catastrophic recovery exit status: %s\n' "$status"
Catastrophic recovery exit status: 0

Do not choose -c because normal recovery failed. Normal recovery failures can mean missing logs, wrong paths, permissions or an environment that is still open. Catastrophic recovery needs a known-good snapshot and the complete subsequent log sequence. If either is missing, involve the person responsible for backups before changing the restored copy.

6. Keep or remove the environment deliberately

By default, recovery does not retain the Berkeley DB environment after it finishes. The -e option retains it. The manpage says this is rarely needed unless a DB_CONFIG file is present; without that file, regions are created with default parameter values.

$ db5.3_recover -e -h "$DB_HOME"
$ printf 'db5.3_recover exit status: %s\n' "$?"
db5.3_recover exit status: 0

Choose -e because the application or recovery procedure requires a retained environment, not because it sounds safer. If you do not know whether the application expects retained regions, use the normal command and check its documented startup procedure.

7. Recover to a specific time when required

The -t option recovers to a timestamp instead of the newest possible point. Its format is [[CC]YY]MMDDhhmm[.SS]. For example, this selects 22 September 2026 at 14:30:00:

$ db5.3_recover -t 202609221430 -h "$DB_HOME"
$ printf 'Time-targeted recovery exit status: %s\n' "$?"
Time-targeted recovery exit status: 0

Be precise about the timestamp. A two-digit year is interpreted using the utility's century rules, an omitted year uses the current year, and omitted seconds default to zero. Time-targeted recovery is easy to misread during an incident, so record the intended time zone and the reason for choosing it before running the command. If you do not have a documented recovery point, omit -t and recover to the most current possible date.

8. Let recovery exit cleanly and start the service

Do not kill a recovery process with an ungraceful signal. The utility needs a chance to detach from the environment and release its resources. If you must stop it, send an interrupt signal, normally with Ctrl-C in the foreground. The manpage specifically identifies SIGINT as the clean-detach path.

Once recovery returns status 0, perform the application's own health check before accepting traffic. A minimal shell checkpoint is:

$ db5.3_recover -h "$DB_HOME"
$ status=$?
$ printf 'status=%s\n' "$status"
status=0
$ test "$status" -eq 0 && printf '%s\n' 'Safe to continue with the application startup check'
Safe to continue with the application startup check

Start the service using its normal account and procedure. Then verify an application-level read and write if the application provides a safe health check. A successful recovery status does not prove that the service configuration, permissions or application schema are correct.