Checkpoint a Berkeley DB 5.3 Environment Safely

You will run db5.3_checkpoint against an existing Berkeley DB environment, either for one immediate checkpoint or as a long-running checkpoint daemon. The examples use Berkeley DB 5.3.28 from the installed db5.3-util package, version 5.3.28+dfsg2-7. Allow about fifteen minutes if the environment path is known.

This utility does not create a database environment or its shared memory regions. The application that owns the environment must start first. You need a readable environment path and the same operating-system access that the database application uses. Run the commands as an ordinary account unless the environment permissions specifically require an administrator.

1. Confirm the installed command

Check the executable and library version before relying on option details:

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

The compatibility name db_checkpoint refers to the same documented utility on this installation. Prefer the versioned command in scripts when you specifically need Berkeley DB 5.3.

2. Identify the environment and its owner

Use the database application's configured home, not an arbitrary directory containing ordinary data files. The utility uses the path from -h. If you omit that option, it uses DB_HOME when set, otherwise the current working directory.

$ DB_HOME='/srv/example-db'
$ test -d "$DB_HOME" && echo 'environment directory exists'
environment directory exists
$ ls -ld "$DB_HOME"
drwx------ 2 dbadmin dbadmin 4096 Sep 22 08:00 /srv/example-db

Replace /srv/example-db with the real path. The ls result only checks the directory entry; it does not prove that a live Berkeley DB environment is open there. Check the service or application documentation to establish the owning account and startup order before continuing.

3. Take one checkpoint and exit

For a maintenance check or a one-off operation, use -1 with the environment path:

$ db5.3_checkpoint -1 -h /srv/example-db
$ printf 'exit status: %s\n' "$?"
exit status: 0

-1 tells the utility to checkpoint once regardless of whether there has been activity, then exit. Success produces no normal output unless you add diagnostic options. A non-zero status means the operation failed, so preserve the error text and investigate before retrying.

This command changes database log state, but it does not remove the environment or delete application records. Do not run it against a path merely because its name looks right. If the command reports that it cannot find the environment, check the path, DB_HOME, permissions and application startup state instead of creating files by hand.

4. Choose a recurring trigger

A daemon needs one of three trigger options. Use -p for an activity-based time interval, -k for log growth, or combine them when both limits matter:

$ db5.3_checkpoint -h /srv/example-db -p 5 -k 10240 -v
checkpoint attempt: 2026-09-22 08:15:00
checkpoint attempt: 2026-09-22 08:20:00

The values above ask for a checkpoint at least every five minutes when there has been activity, and at least as often as every 10,240 kilobytes of log data are written. The exact verbose timestamp format depends on the installed build. With -v, the utility writes the time of each checkpoint attempt to standard output, which is useful when supervising it directly.

• db5.3_checkpoint -p 5 -h /srv/example-db checks the time interval when activity exists.
• db5.3_checkpoint -k 10240 -h /srv/example-db checks log growth.
• db5.3_checkpoint -1 -h /srv/example-db performs one immediate checkpoint and exits.

At least one of -1, -k and -p is required. Running only db5.3_checkpoint -h /srv/example-db fails with a usage message because no checkpoint trigger was selected.

5. Keep the daemon's lifecycle safe

Start the daemon only after the application has opened the environment. For a foreground test, keep the terminal available. When you are finished, send an interrupt so the process can detach from the environment and release its resources:

$ kill -INT CHECKPOINT_PID

Replace CHECKPOINT_PID with the process ID shown by your supervisor. If you launched it in the current shell, press Ctrl-C. Wait for it to exit and verify that it is gone:

$ ps -p CHECKPOINT_PID -o pid=,stat=,cmd=
$ printf 'checkpoint exit status: %s\n' "$?"
checkpoint exit status: 1

The final ps status of 1 means that process no longer exists. Do not send SIGKILL as the first response: the manpage specifically requires an interrupt for a clean detach, helping avoid environment corruption.

6. Handle logging and passwords carefully

Use -L when a supervisor needs a small execution log:

$ db5.3_checkpoint -h /srv/example-db -p 5 -L /var/log/db5.3_checkpoint.log
$ sed -n '1,2p' /var/log/db5.3_checkpoint.log
db_checkpoint: 12345 Tue Sep 22 08:30:00 BST 2026

The process ID and timestamp vary. The log file is removed when the utility exits gracefully, so do not treat it as a permanent audit log. Ensure the selected directory is writable by the account running the utility. Elevated privileges are only appropriate when the existing service account and filesystem policy require them.

If the environment is password-protected, -P accepts its password, but a command-line password can be exposed briefly to other users who can inspect process arguments. Prefer the deployment's existing protected process-supervision mechanism, and do not paste a real password into shell history or an article example. If you must use the option, restrict access to the command and rotate the credential if it was exposed.

7. Diagnose the common failures

A missing trigger is a command-line error:

$ db5.3_checkpoint -h /srv/example-db
BDB5122 db5.3_checkpoint: at least one of -1, -k and -p must be specified
usage: db5.3_checkpoint [-1Vv]
        [-h home] [-k kbytes] [-L file] [-P password] [-p min]

Add the trigger that matches your policy. A missing or unopened environment is different: the process may report that it cannot find the environment or that recovery is required. Check that the application created the environment, that the path is exact, and that you are using the same Berkeley DB family. Do not point a 5.3 utility at an unrelated database directory.

Keep the application's logs and the command's exit status. The utility exits 0 on success and greater than 0 if an error occurs. A successful checkpoint is not a replacement for tested backups or recovery procedures; it only performs the transaction-log checkpoint requested by the utility.