DbEnv::backup()

#include <db_cxx.h>
 
int
DbEnv::backup(const char *target, u_int32_t flags);

The DbEnv::backup() method performs a hot backup of the open environment. All files used by the environment are backed up, so long as the normal rules for file placement are followed. For information on how files are normally placed relative to the environment directory, see Berkeley DB File Naming in the Berkeley DB Programmer's Reference Guide.

By default, data directories and the log directory specified relative to the home directory will be recreated relative to the target directory. If absolute path names are used, then specify DB_BACKUP_SINGLE_DIR to the flags parameter.

This method provides the same functionality as the db_hotbackup utility. However, this method does not perform the housekeeping actions performed by the db_hotbackup utility. In particular, you may want to run a checkpoint before calling this method. To run a checkpoint, use the DbEnv::txn_checkpoint() method. For more information on checkpoints, see Checkpoints in the Berkeley DB Programmer's Reference Guide.

To back up a single database file contained within the environment, use the DbEnv::dbbackup() method.

This method's default behavior can be changed by setting backup callbacks. See DbEnv::set_backup_callbacks() for more information. Additional tuning parameters can also be set using the DbEnv::set_backup_config() method.

The DbEnv::backup() method may only be called after the environment handle has been opened.

The DbEnv::backup() method either returns a non-zero error value or throws an exception that encapsulates a non-zero error value on failure, and returns 0 on success.

Parameters

target

Identifies the directory in which the back up will be placed. Any subdirectories required to contain the backup must be placed relative to this directory. Note that if the backup callbacks are set, then the value specified to this parameter is passed on to the open_func() callback. If this parameter is NULL, then the target must be specified to the open_func() callback.

This directory, and any required subdirectories, will be created for you if you specify the DB_CREATE flag on the call to this method. Otherwise, if the target does not exist, this method exits with an ENOENT error return.

flags

The flags parameter must be set to 0 or by bitwise inclusively OR'ing together one or more of the values:

  • DB_BACKUP_CLEAN

    Before performing the backup, first remove all files from the target backup directory tree.

  • DB_BACKUP_DEEP_COPY

    Copy databases in any sub-directories in the environment home and any supplied data directories.

  • DB_BACKUP_FILES

    Back up all ordinary files that might exist in the environment, and the environment's subdirectories.

  • DB_BACKUP_NO_LOGS

    Back up only the *.db files. Do not backup the log files.

  • DB_BACKUP_SINGLE_DIR

    Regardless of the directory structure used by the source environment, place all back up files in the single directory identified by the target parameter. Use this option if absolute path names to your environment directory and the files within that directory are required by your application.

  • DB_BACKUP_UPDATE

    Perform an incremental back up, instead of a full back up. When this option is specified, only log files are copied to the target directory.

  • DB_CREATE

    If the target directory does not exist, create it and any required subdirectories.

  • DB_EXCL

    Return an EEXIST error if a target backup file already exists.

Errors

The DbEnv::backup() method may fail and throw a DbException exception, encapsulating one of the following non-zero errors, or return one of the following non-zero errors:

EEXIST

DB_EXCL was specified for the flags parameter, and an existing target file was discovered when attempting to back up a source file.

ENOENT

The target directory does not exist and DB_CREATE was not specified for the flags parameter.

EINVAL

An invalid flag value or parameter was specified.

Class

DbEnv

See Also

Database Environments and Related Methods