Oracle Berkeley DB Java Edition

I was searching NoSQL databases and see that Oracle provides a NoSQL database called Berkeley DB. I examined it and wrote a blog to give quick tips to start Java Edition of Berkeley DB. This blog was published in Turkish, about 1 year ago. I’ve decided to translate (in fact, re-write) and publish it in English, and this is what you are reading now.

Berkeley DB is a high-performance embedded database originated at the University of California, Berkeley. It’s fast, reliable and used in several applications such as Evolution (email client), OpenLDAP, RPM (The RPM Package Manager) and Postfix (MTA). In contrast to most other database systems, Berkeley DB provides relatively simple data access services. Berkeley DB databases are B+Trees (like indexes in Oracle RDBMS) and can store only key/value pairs (there are no columns or tables). The keys and values are byte arrays. Databases are stored as files within a single directory which is called “environment”.

There are three versions of Berkeley DB:

  • Berkeley DB (the traditional database, written in C)
  • Berkeley DB Java Edition (native Java version)
  • Berkeley DB XML (for storing XML documents)

As a hobbyist Java programmer, I prefer Berkeley DB Java Edition (JE). Berkeley DB JE supports almost all features of traditional Berkeley DB such as replication, hot-backups, ACID and transactions. It is written in pure Java so it’s platform-independent.

Berkeley DB JE provides two interfaces:

  1. Traditional Berkeley DB API (with DB data abstraction of key/value pairs)
  2. Direct Persistence Layer (DPL) which contains “Plain Old Java Objects” (POJO)

Because I’m an old-school (ex)programmer, I’ll show how to use the traditional Berkeley DB API. Traditional Berkeley DB API will help you understand how Berkeley DB works.

Let’s start by downloading the Berkeley DB from Oracle website:

After you download the file (je-x.x.x.tar.gz/zip), extract it. You’ll find the required JAR file (je-x.x.x.jar) in “lib” folder. You can add it to your Java project and start using Berkeley DB Java Edition.

Berkeley DB stored the datafiles in a folder. We define this folder as an environment object:

Before running the above code, we should be sure that this folder ( “/home/gokhan/berkeleydb” ) exists and our user have required privileges to access it. After you run the code, you’ll see that Berkeley DB created the base files in this folder:

The same code can also be used for “opening” an existing environment. Now we can create (or open) our database in the environment we defined:

As I said Berkeley DB can store key/value pairs. We will use DatabaseEntry object to store key/value pairs. The following code will insert “1” as key and “GOKHAN ATIL” as data:

As you can see, we convert our variables to entries and then use Database object to store them. The “put” method of the Database object is used to insert data:

If the key already exists in the database and no duplicate records are allowed (default), the “put” method will update the existing pair. To read a pair, we need to use “get” method:

To delete records, we can use “delete” method:

Now I’ll combine these functions and write a sample application to generate 500.000 dummy records, insert them into the database and then get a random record:

As you see, Berkeley DB does not have columns, so how can we store a data consisting of multiple columns? We’ll solve this by using TupleInput and TupleOutput objects. Let’s say I want to store name, email and department of employees. First I define an object containing objectToEntry and entryToObject for employee record:

Let’s insert sample records and then try to find (and read) them:

You can find official documents for Berkeley DB Java Edition at Oracle website:

This is just a quick start for Berkeley DB Java Edition. What’s next? Secondary databases, Direct Persistence Layer, cursors, dealing with non-unique keys, transactions… I do not promise but I’ll try to write about these topics in future.

Please share

AWS Big Data Specialist. Oracle Certified Professional (OCP) for EBS R12, Oracle 10g and 11g. Co-author of "Expert Oracle Enterprise Manager 12c" book published by Apress. Awarded as Oracle ACE (in 2011) and Oracle ACE Director (in 2016) for the continuous contributions to the Oracle users community. Founding member, and vice president of Turkish Oracle User Group (TROUG). Presented at various international conferences including Oracle Open World.


  1. rick

    Berkely DB (transactional) has easy corruptibility and recovery is very error prone & tedious and not full proof.

    We tried using in our financial application server it frequently gets corrupted and downtime is significant.Basically for mission critical application where data and availability is critical berkely db is strict no no.

  2. Gokhan:

    Thank you for this post! After reading through the Oracle docs, this really helped me get started with Berkeley DB, especially your examples of TupleOutput and TupleInput from the Bind API.

  3. Eric Ford

    I’m just getting started with BDB JE (v5.0.73) and immediately ran into trouble with the Environment. Apparently, the Environment class (in this version) does NOT support creating the file location. It throws an IllegalArgumentException in the FileManager class if the file does not already exist, regardless of the value input for “setAllowCreate”.

    • Eric Ford

      The setAllowCreate parameter governs whether the files generated by BDB may be created – not the environment path itself.

    • Gokhan Atil

      Yes, it seems you found the answer by yourself. Thanks for sharing.

  4. Santhana


    It’s a great post. The example is very clean and got me through. I have a couple of questions.

    Can we use Berkley DB in web applications?

    And if we can use it, do we still need to pay the licensing fees?

  5. Srimantula


    it s a very good article.

    could you please write a little bit how to view an existed.jdb file

    or how to get the values of an existed .jdb file

    thanking you

  6. keshan

    Hi, This is a great blog.  I’m using @Primary Key(sequence = “ID”) to auto increment the primary key value. But after every database inserted it increment by 100. As a example  1, 101, 201 , 301 etc.  What is wrong, is there any parameter to specify. Please Help me.

    Thank you

  7. Random


    Can u please tell me how to handle images in the database.


    • read the image as byte array

      byte[] sBytes = readImageAsByteArray(sourceImage);

      and create a wrapper class as follows…

      public class Image implements Serializable {
      private int imageId;
      private byte[] imageBytes;

      public int getImageId() {
      return imageId;

      public void setImageId(int imageId) {
      this.imageId = imageId;

      public byte[] getImageBytes() {
      return imageBytes;

      public void setImageBytes(byte[] imageBytes) {
      this.imageBytes = imageBytes;

      public DatabaseEntry objectToEntry() {
      //your wrapper class fields...

      public void entryToObject(DatabaseEntry entry) {
      //your wrapper class fields...

      and by using the following code you can persist your images as byte array…

      // key
      DatabaseEntry key = new DatabaseEntry();
      // data
      DatabaseEntry data = new DatabaseEntry();

      Image img = new Image (1, sBytes)

      // assign 1 to key
      IntegerBinding.intToEntry(1, key);
      // insert into database
      testDB.put(null, key, img.objectToEntry());

  8. vijay

    I am vijay, student . I am working on berkeley java edition . Please can you send me code for Java API .  the one i am working on has problems with

  9. how insert data in database? when i insert data in db ntegerBinding.intToEntry( (1, key); , StringBinding.stringToEntry(“GOKHAN ATIL”, data); testDB.put(ke,data); i faced an error .

  10. Ivo

    Thanks for that blog.
    Can you tell me how to open an existing db4 file with the Java API?

    With Linux command file I have this information:
    $ file myfile
    myfile: Berkeley DB (Btree, version 9, native byte-order)

Leave Comment

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.