Chapter 3. Databases
Prev |  | Next

## Chapter 3. Databases

In Berkeley DB Java Edition, a database is a collection of records. Records, in turn, consist of key/data pairings.

Conceptually, you can think of a `Database` as containing a two-column table where column 1 contains a key and column 2 contains data. Both the key and the data are managed using `DatabaseEntry` class instances (see Database Records for details on this class ). So, fundamentally, using a JE `Database` involves putting, getting, and deleting database records, which in turns involves efficiently managing information encapsulated by `DatabaseEntry` objects. The next several chapters of this book are dedicated to those activities.

Note that on disk, databases are stored in sequentially numerically named log files in the directory where the opening environment is located. JE log files are described Databases and Log Files.

## Opening Databases

You open a database by using the `Environment.openDatabase()` method (environments are described in Database Environments). This method creates and returns a `Database` object handle. You must provide `Environment.openDatabase()` with a database name.

You can optionally provide `Environment.openDatabase()` with a `DatabaseConfig()` object. `DatabaseConfig()` allows you to set properties for the database, such as whether it can be created if it does not currently exist, whether you are opening it read-only, and whether the database is to support transactions.

Note that by default, JE does not create databases if they do not already exist. To override this behavior, set the creation property to true.

Finally, if you configured your environment and database to support transactions, you can optionally provide a transaction object to the `Environment.openDatabase()`. Transactions are described in Transactions later in this manual.

The following code fragment illustrates a database open:

    package com.sleepycat.examples.je.gettingStarted;

    import com.sleepycat.je.Database;
    import com.sleepycat.je.DatabaseConfig;
    import com.sleepycat.je.DatabaseException;
    import com.sleepycat.je.Environment;
    import com.sleepycat.je.EnvironmentConfig;

    import java.io.File;
    ...

    Environment myDbEnvironment = null;
    Database myDatabase = null;

    ...

    try {
        // Open the environment. Create it if it does not already exist.
        EnvironmentConfig envConfig = new EnvironmentConfig();
        envConfig.setAllowCreate(true);
        myDbEnvironment = new Environment(new File("/export/dbEnv"), envConfig);

        // Open the database. Create it if it does not already exist.
        DatabaseConfig dbConfig = new DatabaseConfig();
        dbConfig.setAllowCreate(true);
        myDatabase = myDbEnvironment.openDatabase(null,
                                                  "sampleDatabase",
                                                  dbConfig);
    } catch (DatabaseException dbe) {
        // Exception handling goes here
    }

### Closing Databases

Once you are done using the database, you must close it. You use the `Database.close()` method to do this.

Closing a database causes it to become unusable until it is opened again. If any cursors are opened for the database, JE warns you about the open cursors, and then closes them for you. Active cursors during a database close can cause unexpected results, especially if any of those cursors are writing to the database in another thread. You should always make sure that all your database accesses have completed before closing your database.

Remember that for the same reason, you should always close all your databases before closing the environment to which they belong.

Cursors are described in Using Cursors later in this manual.

The following illustrates database and environment close:

    import com.sleepycat.je.DatabaseException;
    import com.sleepycat.je.Database;
    import com.sleepycat.je.Environment;

    ...

    try {
            if (myDatabase != null) {
                myDatabase.close();
            }

            if (myDbEnvironment != null) {
                myDbEnvironment.close();
            }
    } catch (DatabaseException dbe) {
        // Exception handling goes here
    }

Prev | Up | Next
Database Environment Management Example | Home | Database Properties