Chapter 5. Managing JE Files
Prev |  | Next

## Chapter 5. Managing JE Files

JE is capable of storing several types of files on disk:

- Data files, which contain the actual data in your database.

- Log files, which contain information required to recover your database in the event of a system or application failure.

- Region files, which contain information necessary for the overall operation of your application.

- Temporary files, which are created only under certain special circumstances. These files never need to be backed up or otherwise managed and so they are not a consideration for the topics described in this chapter. See Security Considerations for more information on temporary files.

Of these, you must manage your data and log files by ensuring that they are backed up. You should also pay attention to the amount of disk space your log files are consuming, and periodically remove any unneeded files. Finally, you can optionally tune your logging subsystem to best suit your application's needs and requirements. These topics are discussed in this chapter.

## Checkpoints

Before we can discuss JE file management, we need to describe checkpoints. When databases are modified (that is, a transaction is committed), the modifications are recorded in JE's logs, but they are not necessarily reflected in the actual database files on disk.

This means that as time goes on, increasingly more data is contained in your log files that is not contained in your data files. As a result, you must keep more log files around than you might actually need. Also, any recovery run from your log files will take increasingly longer amounts of time, because there is more data in the log files that must be reflected back into the data files during the recovery process.

You can reduce these problems by periodically running a checkpoint against your environment. The checkpoint:

- Flushes dirty pages from the in-memory cache. This means that data modifications found in your in-memory cache are written to the database files on disk. Note that a checkpoint also causes data dirtied by an uncommitted transaction to also be written to your database files on disk. In this latter case, JE's normal recovery is used to remove any such modifications that were subsequently abandoned by your application using a transaction abort.

  Normal recovery is describe in Recovery Procedures.

- Writes a checkpoint record.

- Flushes the log. This causes all log data that has not yet been written to disk to be written.

- Writes a list of open databases.

There are several ways to run a checkpoint. One way is to use the db_checkpoint command line utility. (Note, however, that this command line utility cannot be used if your environment was opened using `DB_PRIVATE`.)

You can also run a thread that periodically checkpoints your environment for you by calling the `DbEnv::txn_checkpoint()` method.

Note that you can prevent a checkpoint from occurring unless more than a specified amount of log data has been written since the last checkpoint. You can also prevent the checkpoint from running unless more than a specified amount of time has occurred since the last checkpoint. These conditions are particularly interesting if you have multiple threads or processes running checkpoints.

For configuration information, see the DbEnv::txn_checkpoint() API reference page.

Note that running checkpoints can be quite expensive. JE must flush every dirty page to the backing database files. On the other hand, if you do not run checkpoints often enough, your recovery time can be unnecessarily long and you may be using more disk space than you really need. Also, you cannot remove log files until a checkpoint is run. Therefore, deciding how frequently to run a checkpoint is one of the most common tuning activity for JE applications.

For example, to run a checkpoint from a separate thread of control:

    #include <pthread.h>
    #include "db_cxx.h"

    ...

    void *checkpoint_thread(void *);

    int main(void)
    {
        u_int32_t env_flags = DB_CREATE     |  // If the environment does not
                                               // exist, create it.
                              DB_INIT_LOCK  |  // Initialize locking
                              DB_INIT_LOG   |  // Initialize logging
                              DB_INIT_MPOOL |  // Initialize the cache
                              DB_THREAD     |  // Free-thread the env handle
                              DB_INIT_TXN;     // Initialize transactions

        std::string envHome("/export1/testEnv");
        DbEnv myEnv(0);

        try {

            myEnv.open(envHome.c_str(), env_flags, 0);

            // Start a checkpoint thread.
            pthread_t ptid;
            int ret;
            if ((ret = pthread_create(
                &ptid, NULL, checkpoint_thread, (void *)&myEnv)) != 0) {
                    fprintf(stderr,
                        "txnapp: failed spawning checkpoint thread: %s\n",
                        strerror(errno));
                    myEnv.close(0);
                    exit (1);
            }

            // All other threads and application shutdown code
            // omitted for brevity.

            ...
    }

    void *
    checkpoint_thread(void *arg) {
        DbEnv *dbenv = arg;

        // Checkpoint once a minute.
        for (;; sleep(60)) {
            try {
                dbenv->txn_checkpoint(0, 0, 0));
            } catch(DbException &e) {
                dbenv->err(e.get_errno(), "checkpoint thread");
                exit (e.get_errno());
            }
        }

        // NOTREACHED
    }

Prev | Up | Next
Reverse BTree Splits | Home | Backup Procedures