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.

Safety boundary: the output is a backup or migration input, not an atomic snapshot. Do not dump a database while another process is changing it unless you understand that application's consistency guarantees. The recovery options below are more intrusive and can produce misleading data.

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.

Checkpoint: write down the exact input path and, if the listing contains names, the one you intend to export. This stops a later -s option silently selecting the wrong subdatabase.

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.

Warning: do not overwrite the original database by using it as the -f destination.

Recovery: if you wrote a bad dump, remove or rename only the dump file, after checking its path. The source database is not changed by this command.

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.

Warning: do not kill it with SIGKILL during a live environment operation.

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

Warning: these modes do not use database locking. Run them only when no other process can modify the database. The aggressive output will almost certainly need manual editing before reload, so preserve the original file and label the result as untrusted recovery data. Never replace the production database with a salvaged dump as an automatic repair.

7. Account for reload compatibility

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

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.

Recovery: to undo an example in this guide, delete or quarantine only the generated .dump file, after confirming its exact path. There is no database rollback operation because db5.3_dump does not modify the source. If you have already loaded a dump into a test database, discard that test database using the normal procedure for its owning application, not by replacing the production file.

Done means