Inspect Berkeley DB Files and Environments with db5.3_stat

You will use db5.3_stat to inspect a Berkeley DB database file or environment, select the statistic you actually need, and recognise the options that can affect a live system. Allow about 15 minutes for a first inspection, plus time to identify the database file and its home directory. The commands below read state unless an option explicitly resets it.

db_stat is the compatibility name for the same utility on this system. The installed packages are db5.3-util version 5.3.28+dfsg2-7 and db-util version 1:5.3.21ubuntu2. The executable reports Berkeley DB 5.3.28. The local manual pages are dated 28 January 2005, so the examples describe this installed 5.3 utility rather than silently assuming the options of a newer Berkeley DB release.

1. Check the executable and locate the input

Start by confirming which binary will run and which version its library reports. This is an ordinary, unprivileged check. You need read access to the database file or environment, but you do not normally need sudo.

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

Next, identify whether the application uses a standalone database file or a Berkeley DB environment. Look for the application's documented data directory and its configuration, rather than guessing from a filename. Do not copy or edit database files while the application is writing them. If you only need a report from a service-owned directory, arrange read access through the service's normal operational process. Changing ownership or permissions is outside this inspection.

2. Inspect a database file

Use -d when you have a database file. The file argument is required. The command prints database statistics to the terminal and returns zero when it succeeds.

$ db5.3_stat -d /path/to/database.db

The output includes the database type, page count, page size, key and data-item counts, bucket or tree information, overflow pages, and free space. The exact fields depend on the access method and database contents. Values normally shown as byte quantities use GB, MB, KB, or B; other large values can be shown with an M suffix.

Here is a reproducible shape of the result from the installed command, using a small temporary hash database:

$ db5.3_stat -d /tmp/example.db
Tue Sep 22 23:54:40 2026    Local time
61561    Hash magic number
9        Hash version number
Little-endian    Byte order
3        Number of pages in the database
4096     Underlying database page size
2        Number of keys in the database
2        Number of data items in the database

Your timestamp, magic number, counts, and later fields will differ. A successful exit status only says that Berkeley DB could read the requested statistics. It does not prove that the application considers the data logically correct.

3. Select a named database when the file contains several

Berkeley DB files can contain multiple named databases. Add -s with the database name when you need one particular subdatabase:

$ db5.3_stat -d /path/to/container.db -s records

Without -s, the local manual says that a multi-database file is reported through its internal database describing the other databases, not as a single total for the whole file. This is a common source of apparently surprising counts. Obtain the exact name from the application's configuration or its database inventory. Do not invent a name and treat an error as an empty database.

Use -f when you need only statistics that can be collected without traversing the database:

$ db5.3_stat -d /path/to/container.db -s records -f

This is useful for a quick check on a busy or large file. It is a narrower report, not a faster way to obtain every statistic. Compare like-for-like reports when monitoring changes.

4. Inspect an environment subsystem

Use -h to name the Berkeley DB home directory. If you omit it, the utility uses the current working directory, unless DB_HOME is set. That default can be a distraction: running the command from the wrong directory can make it inspect no environment or the wrong one.

$ db5.3_stat -e -h /path/to/db-env

The -e report covers the environment and its configured subsystems. For a narrower view, use one subsystem option at a time:

$ db5.3_stat -m -h /path/to/db-env    # cache statistics
$ db5.3_stat -l -h /path/to/db-env    # logging statistics
$ db5.3_stat -t -h /path/to/db-env    # transaction statistics
$ db5.3_stat -c -h /path/to/db-env    # locking statistics
$ db5.3_stat -r -h /path/to/db-env    # replication statistics

These commands require a real Berkeley DB environment, not merely a directory containing an arbitrary database file. If the home path is wrong, the utility reports an environment-open error. Check the path and the application's environment configuration before trying another option.

5. Treat diagnostic and reset flags as exceptional

Several flags are deliberately not routine monitoring commands. -C, -E, -M, and -R expose internal locking, environment, cache, or replication details and can produce large, low-level output. Use them only when a Berkeley DB specialist or the application's support procedure asks for that specific diagnostic.

Do not use -N as a performance shortcut. It avoids acquiring shared region mutexes and also tells Berkeley DB to ignore other problems, including potentially fatal errors. The local manual marks it for debugging errors only.

Avoid putting a real environment password directly in a command line. The -P option can leave the password briefly visible to users who can inspect process arguments, even though Berkeley DB overwrites the string as soon as possible. Follow the application's approved secret-handling procedure instead. Passwords belong neither in shell history nor in an incident ticket.

6. Handle live environments and failures safely

When inspecting an environment, let the utility detach and exit normally. If it must be interrupted, send SIGINT with Ctrl-C from the terminal so it can release its environment resources cleanly. Do not kill it with an unreviewed forceful signal while it is attached to an active environment.

If a command fails, check the exit status and read the error text:

$ db5.3_stat -d /path/to/database.db
$ printf 'exit=%s\n' "$?"
exit=0

For a non-zero result, check that the path exists, that the file is readable, that the selected subdatabase name is correct, and that the database belongs to the Berkeley DB version in use. A file that is locked, incomplete, or from another format is not repaired by running db5.3_stat again. Preserve the original and use the application's recovery or verification procedure, such as the separately installed db5.3_verify, before making changes.