Isolation
Prev | Chapter 4. Concurrency | Next

## Isolation

Isolation guarantees are an important aspect of transactional protection. Transactions ensure the data your transaction is working with will not be changed by some other transaction. Moreover, the modifications made by a transaction will never be viewable outside of that transaction until the changes have been committed.

That said, there are different degrees of isolation, and you can choose to relax your isolation guarantees to one degree or another depending on your application's requirements. The primary reason why you might want to do this is because of performance; the more isolation you ask your transactions to provide, the more locking that your application must do. With more locking comes a greater chance of blocking, which in turn causes your threads to pause while waiting for a lock. Therefore, by relaxing your isolation guarantees, you can potentially improve your application's throughput. Whether you actually see any improvement depends, of course, on the nature of your application's data and transactions.

### Supported Degrees of Isolation

Sleepycat supports the following levels of isolation:

Degree | ANSI Term | Definition
--- | --- | ---
1 | READ UNCOMMITTED | Uncommitted reads means that one transaction will never overwrite another transaction's dirty data. Dirty data is data that a transaction has modified but not yet committed to the underlying data store. However, uncommitted reads allows a transaction to see data dirtied by another transaction. In addition, a transaction may read data dirtied by another transaction, but which subsequently is aborted by that other transaction. In this latter case, the reading transaction may be reading data that never really existed in the database.
2 | READ COMMITTED | Committed read isolation means that degree 1 is observed, plus data will never change so long as it is addressed by the cursor, but the data may change before the reading cursor is closed. In the case of a transaction, data at the current cursor position will not change, but once the cursor moves, the previous referenced data can change. This means that readers release read locks before the cursor is closed, and therefore, before the transaction completes. Note that this level of isolation causes the cursor to operate in exactly the same way as it does in the absence of a transaction.
3 | SERIALIZABLE | Committed read is observed, plus the data read by a transaction, T, will never be dirtied by another transaction before T completes. This means that both read and write locks are not released until the transaction completes. In addition, no transactions will see phantoms. Phantoms are records returned as a result of a search, but which were not seen by the same transaction when the identical search criteria was previously used. This is JE's default isolation guarantee.

By default, JE transactions and transactional cursors offer serializable isolation. You can optionally reduce your isolation level by configuring JE to use uncommitted read isolation. See Reading Uncommitted Data for more information. You can also configure JE to use committed read isolation. See Committed Reads for more information.

### Reading Uncommitted Data

You can configure your application to read data that has been modified but not yet committed by another transaction; that is, dirty data. When you do this, you may see a performance benefit by allowing your application to not have to block waiting for write locks. On the other hand, the data that your application is reading may change before the transaction has completed.

When used with transactions, uncommitted reads means that one transaction can see data modified but not yet committed by another transaction. When used with transactional cursors, uncommitted reads means that any database reader can see data modified by the cursor before the cursor's transaction has committed.

Because of this, uncommitted reads allow a transaction to read data that may subsequently be aborted by another transaction. In this case, the reading transaction will have read data that never really existed in the database.

To configure your application to read uncommitted data:

1. Open your database such that it will allow uncommitted reads. You do this by specifying `true` to `DatabaseConfig.setReadUncommitted()`.

2. Specify that you want to use uncommitted reads when you create a transaction or open the cursor. To do this, you use the `setReadUncommitted()` method on the relevant configuration object (`TransactionConfig` or `CursorConfig`).

For example, the following opens the database such that it supports uncommitted reads, and then creates a transaction that causes all reads performed within it to use uncommitted reads. Remember that simply opening the database to support uncommitted reads is not enough; you must also declare your read operations to be performed using uncommitted reads.

    package db.txn;

    import com.sleepycat.db.Database;
    import com.sleepycat.db.DatabaseConfig;
    import com.sleepycat.db.DatabaseEntry;
    import com.sleepycat.db.DatabaseException;
    import com.sleepycat.db.Environment;
    import com.sleepycat.db.EnvironmentConfig;
    import com.sleepycat.db.Transaction;
    import com.sleepycat.db.TransactionConfig;

    import java.io.File;

    ...

    Database myDatabase = null;
    Environment myEnv = null;
    try {
        EnvironmentConfig myEnvConfig = new EnvironmentConfig();
        myEnvConfig.setTransactional(true);
        myEnvConfig.setInitializeCache(true);
        myEnvConfig.setInitializeLocking(true);
        myEnvConfig.setInitializeLogging(true);

        myEnv = new Environment(new File("/my/env/home"),
                                  myEnvConfig);

        // Open the database.
        DatabaseConfig dbConfig = new DatabaseConfig();
        dbConfig.setTransactional(true);
        dbConfig.setType(DatabaseType.BTREE);
        dbConfig.setReadUncommitted(true);      // Enable uncommitted reads.
        myDatabase = myEnv.openDatabase(null,              // txn handle
                                        "sampleDatabase",  // db file name
                                        null,              // db name
                                        dbConfig);
        Transaction txn = null;
        TransactionConfig txnConfig = new TransactionConfig();
        txnConfig.setReadUncommitted(true);          // Use uncommitted reads
                                                     // for this transaction.
        txn = myEnv.beginTransaction(null, txnConfig);

        // From here, you perform your database reads and writes as normal,
        // committing and aborting the transactions as is necessary, and
        // testing for deadlock exceptions as normal (omitted for brevity).

        ...

You can also configure uncommitted read isolation on a read-by-read basis by specifying `LockMode.READ_UNCOMMITTED`:

    package db.txn;

    import com.sleepycat.db.Database;
    import com.sleepycat.db.DatabaseEntry;
    import com.sleepycat.db.Environment;
    import com.sleepycat.db.LockMode;
    import com.sleepycat.db.Transaction;

    ...

    Database myDb = null;
    Environment myEnv = null;
    Transaction txn = null;

    try {

        // Environment and database open omitted

        ...

        txn = myEnv.beginTransaction(null, null);

        DatabaseEntry theKey =
            new DatabaseEntry((new String("theKey")).getBytes("UTF-8"));
        DatabaseEntry theData = new DatabaseEntry();

        myDb.get(txn, theKey, theData, LockMode.READ_UNCOMMITTED);
    } catch (Exception e) {
        // Exception handling goes here
    }

### Committed Reads

You can configure your transaction so that the data being read by a transactional cursor is consistent so long as it is being addressed by the cursor. However, once the cursor is done reading the record (that is, reading records from the page that it currently has locked), the cursor releases its lock on that record or page. This means that the data the cursor has read and released may change before the cursor's transaction has completed.

For example, suppose you have two transactions, `Ta` and `Tb`. Suppose further that `Ta` has a cursor that reads `record R`, but does not modify it. Normally, `Tb` would then be unable to write `record R` because `Ta` would be holding a read lock on it. But when you configure your transaction for committed reads, `Tb` can modify `record R` before `Ta` completes, so long as the reading cursor is no longer addressing the record or page.

When you configure your application for this level of isolation, you may see better performance throughput because there are fewer read locks being held by your transactions. Read committed isolation is most useful when you have a cursor that is reading and/or writing records in a single direction, and that does not ever have to go back to re-read those same records. In this case, you can allow JE to release read locks as it goes, rather than hold them for the life of the transaction.

To configure your application to use committed reads, do one of the following:

- Create your transaction such that it allows committed reads. You do this by specifying `true` to `TransactionConfig.setReadCommitted()`.

- Specify `true` to `CursorConfig.setReadCommitted()`.

For example, the following creates a transaction that allows committed reads:

    package db.txn;

    import com.sleepycat.db.Database;
    import com.sleepycat.db.DatabaseConfig;
    import com.sleepycat.db.DatabaseEntry;
    import com.sleepycat.db.DatabaseException;
    import com.sleepycat.db.Environment;
    import com.sleepycat.db.EnvironmentConfig;
    import com.sleepycat.db.Transaction;
    import com.sleepycat.db.TransactionConfig;

    import java.io.File;

    ...

    Database myDatabase = null;
    Environment myEnv = null;
    try {
        EnvironmentConfig myEnvConfig = new EnvironmentConfig();
        myEnvConfig.setTransactional(true);
        myEnvConfig.setInitializeCache(true);
        myEnvConfig.setInitializeLocking(true);
        myEnvConfig.setInitializeLogging(true);

        myEnv = new Environment(new File("/my/env/home"),
                                  myEnvConfig);

        // Open the database.
        // Notice that we do not have to specify any properties to the
        // database to allow committed reads (this is as opposed to
        // uncommitted reads where we DO have to specify a property on
        // the database open.
        DatabaseConfig dbConfig = new DatabaseConfig();
        dbConfig.setTransactional(true);
        dbConfig.setType(DatabaseType.BTREE);

        myDatabase = myEnv.openDatabase(null,              // txn handle
                                        "sampleDatabase",  // db file name
                                        null,              // db name
                                        dbConfig);
        String keyString = "thekey";
        String dataString = "thedata";
        DatabaseEntry key =
            new DatabaseEntry(keyString.getBytes("UTF-8"));
        DatabaseEntry data =
            new DatabaseEntry(dataString.getBytes("UTF-8"));

        Transaction txn = null;
        TransactionConfig txnConfig = new TransactionConfig();

        // Open the transaction and enable committed reads. All cursors open
        // with this transaction handle will use read committed isolation.
        txnConfig.setReadCommitted(true);
        txn = myEnv.beginTransaction(null, txnConfig);

        // From here, you perform your database reads and writes as normal,
        // committing and aborting the transactions as is necessary, and
        // testing for deadlock exceptions as normal (omitted for brevity).

        // Using transactional cursors with concurrent applications is
        // described in more detail in the following section.

        ...

You can also configure read committed isolation on a read-by-read basis by specifying `LockMode.READ_COMMITTED`:

    package db.txn;

    import com.sleepycat.db.Database;
    import com.sleepycat.db.DatabaseEntry;
    import com.sleepycat.db.Environment;
    import com.sleepycat.db.LockMode;
    import com.sleepycat.db.Transaction;

    ...

    Database myDb = null;
    Environment myEnv = null;
    Transaction txn = null;

    try {

        // Environment and database open omitted

        ...

        txn = myEnv.beginTransaction(null, null);

        DatabaseEntry theKey =
            new DatabaseEntry((new String("theKey")).getBytes("UTF-8"));
        DatabaseEntry theData = new DatabaseEntry();

        myDb.get(txn, theKey, theData, LockMode.READ_COMMITTED);
    } catch (Exception e) {
        // Exception handling goes here
    }

Prev | Up | Next
The Locking Subsystem | Home | Transactional Cursors and Concurrent Applications