Back Up a Berkeley DB File with db5.3_dump

Copying a Berkeley DB file with cp gives you a backup you cannot trust, and db5.3_dump gives you one you can reload. You will finish with a portable flat-text dump and a quick check that it contains the database you meant to copy. Allow about fifteen minutes for a normal export and verification.

The examples use db5.3_dump from Berkeley DB 5.3.28, installed here from db5.3-util version 5.3.28+dfsg2-7. The db_dump command supplied by db-util reports the same library version and is an alias for this guide's command.

You need a readable Berkeley DB file and enough free space for the dump. A routine dump does not need root privileges. Use elevated privileges only when the database is deliberately restricted and you have confirmed that reading it as root is appropriate.

1. Confirm the installed command and version

Check the binary before building a script around it. This is read-only:

$ command -v db5.3_dump
/usr/bin/db5.3_dump
$ db5.3_dump -V
Berkeley DB 5.3.28: (September  9, 2013)
$ 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

The version matters when you move dumps between hosts. Keep the command name explicit in automation if you need Berkeley DB 5.3 rather than whichever unversioned utility a package happens to provide.

2. List subdatabases before exporting

A Berkeley DB file can contain one database or several named subdatabases. Ask for the names first:

$ db5.3_dump -l /path/to/data.db
database_name_one
database_name_two

The names above are examples; the command prints the names found in your file. An error such as does not contain multiple databases means this is a single-database file, not that the file is necessarily unusable. If you have a single database, continue without -s.

3. Create the ordinary portable dump

Use -f to write the dump to a new path. Choose a destination on the same protected storage policy as the database, or send it to your backup system:

$ db5.3_dump -f /path/to/data.db.dump /path/to/data.db
$ test -s /path/to/data.db.dump
$ printf 'dump exit status: %s\n' "$?"
dump exit status: 0

Without -f, the dump goes to standard output. That suits a pipe, but it is easy to lose or mix with diagnostic output.

The normal dump format is intended for db5.3_load. It includes metadata such as the format version and access method, followed by the records.

4. Select one database when the file contains several

Once you have checked the names with -l, add -s for a single subdatabase:

$ db5.3_dump -s database_name_one \
    -f /path/to/database_name_one.dump \
    /path/to/data.db
$ head -8 /path/to/database_name_one.dump
VERSION=3
format=bytevalue
type=hash
HEADER=END

The selected name must match the listing exactly. Leaving out -s exports all databases in the file. That is usually the safest choice for a complete backup, while a named export suits migrating one application database.

To inspect printable key and data values, use -p:

$ db5.3_dump -p /path/to/data.db > /tmp/data-readable.dump
$ sed -n '1,12p' /tmp/data-readable.dump
VERSION=3
format=print

-p makes printable bytes easier to read and edit, but the definition of printable differs between systems. The result can be less portable than the default byte-value form. Treat a human-readable dump as an inspection copy unless you have tested its reload.

5. Verify the dump without changing the source

Check that the output is non-empty, has the expected format markers, and names the expected access method:

$ test -s /path/to/data.db.dump
$ grep -E '^(VERSION|format|type|HEADER|DATA)=' /path/to/data.db.dump
VERSION=3
format=bytevalue
type=hash
HEADER=END
DATA=END

The exact header fields vary with database type and options. A zero exit status from db5.3_dump means the utility completed successfully; it does not prove the application can use a restored database. For higher confidence, restore into a disposable path or test environment with the matching db5.3_load version, then run the application's own checks.

If the database is inside a Berkeley DB environment, let the utility detach cleanly. Pressing Ctrl-C sends SIGINT and gives it the documented chance to release environment resources.

6. Handle damaged files carefully

The ordinary command is for a readable database. For a possibly corrupt file, -r attempts salvage and normally returns equivalent data for an uncorrupted database, but ordering may differ. -R is more aggressive and can include deleted or nonsensical items:

$ db5.3_dump -r -f /safe/recovery/data.salvaged.dump /path/to/damaged.db
$ db5.3_dump -R -f /safe/recovery/data.aggressive.dump /path/to/damaged.db

• -d is for Berkeley DB library debugging, not backup. Its output is non-standard and may change between releases.
• -N disables shared region mutex acquisition and is intended only for debugging potentially fatal errors. Do not add it to a normal export.

7. Account for reload compatibility

A dump and reload can change behaviour when the original database used application-supplied functions:

• Hash databases with a user-defined hash function reload with the default hash function.
• Btree databases with user-defined prefix or comparison functions reload with the defaults, and the result can be unusable.

Before relying on a migration, identify whether the application supplied any of those functions, and test the restored copy with the application.

For Queue or Recno databases, -k includes record numbers as keys. This can help when converting those databases to Btree or Hash with db5.3_load, but it changes the dump's representation. Use it only when the target format requires record-number keys.