Java Binding

The official Java binding for RocksDB provides a comprehensive API for JVM-based applications. It includes full support for core RocksDB features including transactions, column families, iterators, and advanced configuration options.

Installation

Maven
Gradle
SBT

Add RocksDB as a dependency in your pom.xml:

<dependency>
  <groupId>org.rocksdb</groupId>
  <artifactId>rocksdbjni</artifactId>
  <version>9.10.0</version>
</dependency>

Add RocksDB to your build.gradle:

dependencies {
    implementation 'org.rocksdb:rocksdbjni:9.10.0'
}

Add RocksDB to your build.sbt:

libraryDependencies += "org.rocksdb" % "rocksdbjni" % "9.10.0"

The rocksdbjni package includes native libraries for Linux, macOS, and Windows. The correct native library is loaded automatically at runtime.

Quick Start

Basic Operations

import org.rocksdb.*;

public class RocksDBExample {
  static {
    RocksDB.loadLibrary();
  }

  public static void main(String[] args) {
    try (final Options options = new Options().setCreateIfMissing(true);
         final RocksDB db = RocksDB.open(options, "/path/to/db")) {
      
      // Put a key-value pair
      db.put("hello".getBytes(), "world".getBytes());
      
      // Get a value
      byte[] value = db.get("hello".getBytes());
      System.out.println("Value: " + new String(value));
      
      // Delete a key
      db.delete("hello".getBytes());
      
    } catch (RocksDBException e) {
      System.err.println("Error: " + e.getMessage());
    }
  }
}

Configuring Options

import org.rocksdb.*;
import org.rocksdb.util.SizeUnit;

try (final Options options = new Options()) {
  options.setCreateIfMissing(true)
      .setWriteBufferSize(8 * SizeUnit.KB)
      .setMaxWriteBufferNumber(3)
      .setMaxBackgroundJobs(10)
      .setCompressionType(CompressionType.ZLIB_COMPRESSION)
      .setCompactionStyle(CompactionStyle.UNIVERSAL);
      
  try (final RocksDB db = RocksDB.open(options, dbPath)) {
    // Use database
  }
} catch (RocksDBException e) {
  e.printStackTrace();
}

import org.rocksdb.*;

try (final Options options = new Options();
     final Filter bloomFilter = new BloomFilter(10);
     final Cache cache = new LRUCache(64 * 1024 * 1024)) {
     
  BlockBasedTableConfig tableConfig = new BlockBasedTableConfig()
      .setBlockCache(cache)
      .setFilterPolicy(bloomFilter)
      .setBlockSizeDeviation(5)
      .setBlockRestartInterval(10)
      .setCacheIndexAndFilterBlocks(true);
      
  options.setTableFormatConfig(tableConfig);
  
  try (final RocksDB db = RocksDB.open(options, dbPath)) {
    // Use database
  }
} catch (RocksDBException e) {
  e.printStackTrace();
}

import org.rocksdb.*;

try (final Options options = new Options();
     final Statistics stats = new Statistics()) {
     
  options.setStatistics(stats).setCreateIfMissing(true);
  
  try (final RocksDB db = RocksDB.open(options, dbPath)) {
    // Perform operations...
    
    // Get statistics
    for (TickerType ticker : TickerType.values()) {
      if (ticker != TickerType.TICKER_ENUM_MAX) {
        long count = stats.getTickerCount(ticker);
        System.out.println(ticker + ": " + count);
      }
    }
  }
} catch (RocksDBException e) {
  e.printStackTrace();
}

Advanced Features

Column Families

Column families allow you to logically partition your data within a single database:

import org.rocksdb.*;
import java.util.*;

RocksDB.loadLibrary();

// Open DB with multiple column families
List<ColumnFamilyDescriptor> cfDescriptors = Arrays.asList(
    new ColumnFamilyDescriptor(RocksDB.DEFAULT_COLUMN_FAMILY, new ColumnFamilyOptions()),
    new ColumnFamilyDescriptor("new_cf".getBytes(), new ColumnFamilyOptions())
);

List<ColumnFamilyHandle> cfHandles = new ArrayList<>();

try (final DBOptions options = new DBOptions();
     final RocksDB db = RocksDB.open(options, dbPath, cfDescriptors, cfHandles)) {
     
  // Write to specific column family
  db.put(cfHandles.get(1), "key".getBytes(), "value".getBytes());
  
  // Atomic write across column families
  try (final WriteBatch batch = new WriteBatch()) {
    batch.put(cfHandles.get(0), "key1".getBytes(), "value1".getBytes());
    batch.put(cfHandles.get(1), "key2".getBytes(), "value2".getBytes());
    db.write(new WriteOptions(), batch);
  }
  
  // Drop column family
  db.dropColumnFamily(cfHandles.get(1));
  
} catch (RocksDBException e) {
  e.printStackTrace();
} finally {
  for (ColumnFamilyHandle handle : cfHandles) {
    handle.close();
  }
}

Transactions

RocksDB supports ACID transactions with snapshot isolation:

import org.rocksdb.*;
import static java.nio.charset.StandardCharsets.UTF_8;

try (final Options options = new Options().setCreateIfMissing(true);
     final TransactionDBOptions txnDbOptions = new TransactionDBOptions();
     final TransactionDB txnDb = TransactionDB.open(options, txnDbOptions, dbPath)) {
     
  try (final WriteOptions writeOptions = new WriteOptions();
       final ReadOptions readOptions = new ReadOptions()) {
       
    // Start a transaction
    try (final Transaction txn = txnDb.beginTransaction(writeOptions)) {
      
      // Read a key in this transaction
      byte[] value = txn.get(readOptions, "key1".getBytes(UTF_8));
      
      // Write a key in this transaction
      txn.put("key1".getBytes(UTF_8), "value1".getBytes(UTF_8));
      
      // Commit transaction
      txn.commit();
    }
  }
} catch (RocksDBException e) {
  e.printStackTrace();
}

import org.rocksdb.*;
import static java.nio.charset.StandardCharsets.UTF_8;

try (final TransactionDBOptions txnDbOptions = new TransactionDBOptions();
     final TransactionDB txnDb = TransactionDB.open(options, txnDbOptions, dbPath)) {
     
  // Set snapshot at start of transaction
  try (final TransactionOptions txnOptions = new TransactionOptions().setSetSnapshot(true);
       final Transaction txn = txnDb.beginTransaction(writeOptions, txnOptions)) {
       
    final Snapshot snapshot = txn.getSnapshot();
    readOptions.setSnapshot(snapshot);
    
    try {
      // This read uses the snapshot
      byte[] value = txn.getForUpdate(readOptions, "key".getBytes(UTF_8), true);
      
      txn.commit();
    } catch (RocksDBException e) {
      if (e.getStatus().getCode() == Status.Code.Busy) {
        // Conflict detected
        txn.rollback();
      }
    } finally {
      readOptions.setSnapshot(null);
    }
  }
} catch (RocksDBException e) {
  e.printStackTrace();
}

import org.rocksdb.*;

try (final Transaction txn = txnDb.beginTransaction(writeOptions)) {
  
  txn.put("key1".getBytes(), "value1".getBytes());
  
  // Create a save point
  txn.setSavePoint();
  
  txn.put("key2".getBytes(), "value2".getBytes());
  
  // Rollback to save point (key2 not written)
  txn.rollbackToSavePoint();
  
  // Commit (only key1 is written)
  txn.commit();
  
} catch (RocksDBException e) {
  e.printStackTrace();
}

Iterators

Iterate over keys and values efficiently:

import org.rocksdb.*;

try (final RocksDB db = RocksDB.open(options, dbPath);
     final RocksIterator iterator = db.newIterator()) {
     
  // Iterate forward from the first key
  for (iterator.seekToFirst(); iterator.isValid(); iterator.next()) {
    byte[] key = iterator.key();
    byte[] value = iterator.value();
    System.out.println(new String(key) + " => " + new String(value));
  }
  
  // Iterate backward from the last key
  for (iterator.seekToLast(); iterator.isValid(); iterator.prev()) {
    byte[] key = iterator.key();
    byte[] value = iterator.value();
    System.out.println(new String(key) + " => " + new String(value));
  }
  
  // Seek to a specific key
  iterator.seek("prefix".getBytes());
  if (iterator.isValid()) {
    System.out.println("Found: " + new String(iterator.key()));
  }
  
} catch (RocksDBException e) {
  e.printStackTrace();
}

Write Batches

Group multiple writes into an atomic operation:

import org.rocksdb.*;

try (final RocksDB db = RocksDB.open(options, dbPath);
     final WriteOptions writeOpts = new WriteOptions();
     final WriteBatch batch = new WriteBatch()) {
     
  // Add operations to batch
  batch.put("key1".getBytes(), "value1".getBytes());
  batch.put("key2".getBytes(), "value2".getBytes());
  batch.delete("key3".getBytes());
  
  // Apply all operations atomically
  db.write(writeOpts, batch);
  
} catch (RocksDBException e) {
  e.printStackTrace();
}

Multi-Get Operations

Retrieve multiple values in a single operation:

import org.rocksdb.*;
import java.util.*;

try (final RocksDB db = RocksDB.open(options, dbPath)) {
  
  List<byte[]> keys = Arrays.asList(
      "key1".getBytes(),
      "key2".getBytes(),
      "key3".getBytes()
  );
  
  // Get multiple values at once
  List<byte[]> values = db.multiGetAsList(keys);
  
  for (int i = 0; i < keys.size(); i++) {
    byte[] value = values.get(i);
    if (value != null) {
      System.out.println(new String(keys.get(i)) + " => " + new String(value));
    }
  }
  
} catch (RocksDBException e) {
  e.printStackTrace();
}

Resource Management

RocksDB objects must be explicitly closed to prevent memory leaks. Always use try-with-resources or explicitly call close().

The Java binding uses JNI to interact with the native RocksDB library. All RocksDB objects extend RocksObject or AbstractNativeReference and must be properly disposed:

// Good: Using try-with-resources
try (final Options options = new Options();
     final RocksDB db = RocksDB.open(options, dbPath)) {
  // Use database
} catch (RocksDBException e) {
  e.printStackTrace();
}

// Also acceptable: Manual cleanup
Options options = new Options();
RocksDB db = null;
try {
  db = RocksDB.open(options, dbPath);
  // Use database
} catch (RocksDBException e) {
  e.printStackTrace();
} finally {
  if (db != null) db.close();
  options.close();
}

Understanding Options

Database Options

Database-wide settings that affect the entire RocksDB instance, including I/O, background jobs, and logging.

Column Family Options

Per-column-family settings for compression, memtables, and compaction. These can be configured independently for each column family.

Mutable Options

Options that can be changed on a running database using setOptions() or setDBOptions() without restarting.

Advanced Options

Fine-tuning options for performance optimization, memory management, and specialized use cases.

Options Hierarchy

The Options class combines both DBOptions and ColumnFamilyOptions:

// Options = DBOptions + ColumnFamilyOptions
Options options = new Options();
  .setCreateIfMissing(true)      // DB option
  .setWriteBufferSize(64 * 1024) // CF option
  .setMaxBackgroundJobs(4);      // DB option

// Or use separate options for more control
DBOptions dbOptions = new DBOptions().setCreateIfMissing(true);
ColumnFamilyOptions cfOptions = new ColumnFamilyOptions().setWriteBufferSize(64 * 1024);

Many options that appear as database options actually apply as defaults for column families. See the understanding_options.md guide for details.

Platform Support

The Java binding includes native libraries for:

Linux (x86_64, ARM64)
macOS (x86_64, ARM64)
Windows (x86_64)

The correct native library is automatically loaded based on your platform.

Resources

Source Code

Browse the Java binding source code on GitHub

Java API Samples

Complete working examples demonstrating key features

Benchmarks

Performance benchmarks and optimization tips

Release History

Changelog and version history for Java binding

Next Steps

Configuration

Learn about RocksDB configuration options

Performance Tuning

Optimize RocksDB for your workload

Transactions

Deep dive into transaction semantics

Column Families

Advanced column family usage patterns

Get Started

Core Concepts

Developer Guide

Advanced Topics

Language Bindings

Tools & Utilities

Installation

Quick Start

Basic Operations

Configuring Options

Advanced Features

Column Families

Transactions

Iterators

Write Batches

Multi-Get Operations

Resource Management

Understanding Options

Database Options

Column Family Options

Mutable Options

Advanced Options

Options Hierarchy

Platform Support

Resources

Source Code

Java API Samples

Benchmarks

Release History

Next Steps

Configuration

Performance Tuning

Transactions

Column Families

​Installation

​Quick Start

​Basic Operations

​Configuring Options

​Advanced Features

​Column Families

​Transactions

​Iterators

​Write Batches

​Multi-Get Operations

​Resource Management

​Understanding Options

Database Options

Column Family Options

Mutable Options

Advanced Options

​Options Hierarchy

​Platform Support

​Resources

Source Code

Java API Samples

Benchmarks

Release History

​Next Steps

Configuration

Performance Tuning

Transactions

Column Families

Installation

Quick Start

Basic Operations

Configuring Options

Advanced Features

Column Families

Transactions

Iterators

Write Batches

Multi-Get Operations

Resource Management

Understanding Options

Options Hierarchy

Platform Support

Resources

Next Steps