Hot backup

WiredTiger cursors provide access to data from a variety of sources.

One of these sources is the list of files required to perform a hot backup of the database. The list may be the files required by all of the objects in the database, or a subset of the objects in the database.

To perform a hot backup:

1. Open a cursor on the "backup:" data source, which begins the process of a hot backup.
2. Copy each file returned by the WT_CURSOR::next method to the hot backup location, for example, a different directory.
3. Close the cursor; the cursor must not be closed until all of the files have been copied.

A directory to which the files are copied may subsequently be specified as an directory to the wiredtiger_open function and accessed as a WiredTiger database home.

Notes:

• Copying the database files for a hot backup does not require any special alignment or block size (specifically, Linux or Windows filesystems that do not support read/write isolation can be safely read for hot backups).
• The cursor must not be closed until all of the files have been copied, however, there is no requirement the files be copied in any order or in any relationship to the WT_CURSOR::next calls, only that all files have been copied before the cursor is closed. For example, applications might aggregate the file names from the cursor and then list the file names as arguments to a file archiver such as the system tar utility.
• During the period the hot backup cursor is open, database checkpoints can be created, but no checkpoints can be deleted. This may result in significant file growth.
• Many Linux systems do not support mixing O_DIRECT and memory mapping or normal I/O to the same file. If O_DIRECT is configured for data files on Linux systems (using the wiredtiger_open direct_io configuration), the utilities used to copy the database files should probably also specify O_DIRECT when configuring their file access.

The following is a programmatic example of creating a hot backup:

        WT_CURSOR *cursor;
        const char *filename;
        int ret;

        /* Create the backup directory. */
        ret = mkdir("/path/database.backup", 077);

        /* Open the hot backup data source. */
        ret = session->open_cursor(session, "backup:", NULL, NULL, &cursor);

        /* Copy the list of files. */
        while (
            (ret = cursor->next(cursor)) == 0 &&
            (ret = cursor->get_key(cursor, &filename)) == 0) {
                (void)snprintf(buf, sizeof(buf),
                    "cp /path/database/%s /path/database.backup/%s",
                    filename, filename);
                ret = system(buf);
        }
        if (ret == WT_NOTFOUND)
                ret = 0;
        if (ret != 0)
                fprintf(stderr, "%s: cursor next(backup:) failed: %s\n",
                    progname, wiredtiger_strerror(ret));

        ret = cursor->close(cursor);

In cases where the backup is desired for a checkpoint other than the most recent, applications can discard all checkpoints subsequent to the checkpoint they want using the WT_SESSION::checkpoint method. For example:

        ret = session->checkpoint(session, "drop=(from=June01),name=June01");

Hot backup from the command line

The wt backup command may also be used to create hot backups:

rm -rf /path/database.backup &&
    mkdir /path/database.backup &&
    wt -h /path/database.source backup /path/database.backup