Upgrade Berkeley DB 5.3 Files Without Losing the Original

You will finish with a backed-up Berkeley DB file upgraded for the Berkeley DB 5.3 library, plus a verification record showing which command and release performed the work. The installed utility is db5.3_upgrade, from db5.3-util version 5.3.28+dfsg2-7. The db_upgrade name is an alias to the same executable on this machine.

Allow about fifteen minutes for one small file, plus the time needed to make and check a real backup. You need shell access, enough free space for at least one complete copy, and a Berkeley DB file that is not being written by an application. The upgrade changes the database in place. It is potentially destructive and cannot be treated like a read-only format check.

1. Confirm the installed utility

Start with read-only checks. No elevated privileges are normally needed if the database belongs to your account:

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

The version printed by -V is the library version used by the utility. Package revisions and the date in that line can differ on another distribution. Keep this output with your change record, especially when an application was built against an older Berkeley DB release.

Checkpoint: if db5.3_upgrade -V does not report the release you expect, stop. Do not compensate by adding flags to an unverified binary.

2. Stop writers and locate the database

Choose the exact physical file or files to upgrade. Stop the application, worker or service that can open them, and make sure no scheduled job will restart it during the operation. This is the service-disrupting part of the procedure. The utility accepts one or more files, but begin with one file unless you have already tested the batch.

$ DB_FILE='/srv/example/data/catalog.db'
$ test -f "$DB_FILE" && printf '%s\n' 'database file found'
database file found
$ stat --format='size=%s bytes mode=%a path=%n' "$DB_FILE"
size=... bytes mode=... path=/srv/example/data/catalog.db

Replace the placeholder with your real path. Do not infer a database file from a directory listing alone: one Berkeley DB physical file can contain more than one database, and upgrading the file affects all databases inside it.

If the application uses a Berkeley DB environment, identify its home directory as well. The utility uses -h when supplied, otherwise DB_HOME if set, and otherwise the current working directory. A wrong home directory can make an otherwise valid file fail or attach to the wrong environment.

3. Make a recoverable copy

Do this before the upgrade. The copy must be made while writers are stopped, and it should be on storage with enough free space. Keep the original backup until the upgraded database has passed application-level checks.

$ BACKUP='/srv/example/data/catalog.db.before-db5.3-upgrade'
$ cp --preserve=all -- "$DB_FILE" "$BACKUP"
$ cmp -- "$DB_FILE" "$BACKUP" && printf '%s\n' 'backup matches source'
backup matches source
$ stat --format='backup size=%s bytes path=%n' "$BACKUP"
backup size=... bytes path=/srv/example/data/catalog.db.before-db5.3-upgrade

The cmp result proves that this copy matched the source at the time it was made. It does not prove that either file is a valid database, and it does not protect against a storage failure affecting both paths. For a production environment, use your normal tested backup or snapshot process as well.

Do not remove the backup as part of a script. If the upgrade fails, or if the application behaves incorrectly afterwards, stop the application and restore it only after preserving the failed file for investigation:

$ mv -- "$DB_FILE" "$DB_FILE.failed-db5.3-upgrade"
$ cp --preserve=all -- "$BACKUP" "$DB_FILE"
$ cmp -- "$DB_FILE" "$BACKUP" && printf '%s\n' 'original copy restored'
original copy restored

Restoring is a state-changing operation. Recheck ownership, permissions, environment logs and application compatibility before starting the service again. If the file is owned by a service account, these commands may require sudo; use elevated privileges only for the paths that require them.

4. Upgrade the file with the ordinary path

Run the utility from a maintenance shell with writers still stopped:

$ db5.3_upgrade -v "$DB_FILE"
db5.3_upgrade: ...

The verbose line is deliberately shown with an ellipsis because its exact wording depends on the file and the installed utility. The useful success signal is exit status 0:

$ status=$?
$ printf 'upgrade exit status: %s\n' "$status"
upgrade exit status: 0

The command has no dry-run mode in the installed interface. It upgrades in place, and a crash or exhausted filesystem can leave the database inconsistent and unrecoverable. Do not interrupt it casually. If the file belongs to a Berkeley DB environment, the manual specifically says to give the process a chance to detach cleanly; send SIGINT when you need it to release environment resources and exit, rather than killing it with an unconditional termination signal.

If the command reports an error, preserve the file and its output. Do not immediately retry over the same copy. Compare the failure with the untouched backup, check free space and permissions, and decide whether restoring or using a dump-and-load migration is safer.

5. Supply an environment home when required

If the database is managed inside a Berkeley DB environment, make the home explicit instead of relying on the shell's current directory:

$ DB_HOME='/srv/example/data/environment'
$ db5.3_upgrade -h "$DB_HOME" -v "$DB_FILE"
db5.3_upgrade: ...

This example assumes the file path and environment home are correct for your deployment. Check the utility's current directory and environment variables before running it:

$ printf 'home=%s\nfile=%s\n' "$DB_HOME" "$DB_FILE"
home=/srv/example/data/environment
file=/srv/example/data/catalog.db

Do not pass -N for a normal upgrade. It disables shared region mutex acquisition and tells Berkeley DB to ignore other potentially fatal problems. The manpage marks it for debugging only; it is not a way to make a busy environment safe.

6. Treat old duplicate formats as a special case

The -s option matters only when upgrading databases from before Berkeley DB 3.1. It says that duplicate data items are sorted; without it they are assumed to be unsorted. Choosing incorrectly can corrupt the database.

The decision applies to the whole physical file, including every database it contains. If one database uses sorted duplicates and another uses unsorted duplicates, this utility cannot safely represent both choices for that file. Follow the dump-and-load migration documented for your old release instead. Do not guess based on the file name or add -s because a command example happened to include it.

7. Verify before restarting the service

First record the exit code and check that the file remains present:

$ test "$status" -eq 0
$ test -f "$DB_FILE" && printf '%s\n' 'upgraded file is present'
upgraded file is present
$ stat --format='size=%s bytes path=%n' "$DB_FILE"
size=... bytes path=/srv/example/data/catalog.db

Then run the database's own verification and an application-level read-only smoke test, using the same Berkeley DB family where possible. A successful upgrade exit status means the utility completed; it does not prove that your application expects the resulting format, permissions or contents.

Keep the backup while the service starts in a maintenance window. Watch its logs, exercise a read path, and test a representative write only after the read checks pass. If anything is wrong, stop the service, preserve the upgraded file, restore the backup, and investigate before retrying.