MapDB

Language: Java

Data / Embedded Database / Caching

MapDB was created to offer a lightweight, fast, and thread-safe Java storage solution for applications needing persistent collections or in-memory caching. It combines features of a database and a cache, allowing developers to manage large datasets efficiently without relying on external database servers.

MapDB is an embedded Java database and caching library that provides fast, concurrent, and off-heap key-value storage. It supports maps, sets, queues, and other collections with optional persistence to disk or memory-mapped files.

Installation

maven:

<dependency>
  <groupId>org.mapdb</groupId>
  <artifactId>mapdb</artifactId>
  <version>3.0.9</version>
</dependency>

gradle: implementation 'org.mapdb:mapdb:3.0.9'

Usage

MapDB provides concurrent collections (maps, sets, queues) with optional persistence. It supports transactions, snapshots, off-heap memory, and disk-backed storage. Developers can use it as an embedded database for small to medium-sized applications or as a high-performance cache for large datasets.

Creating a persistent map

import org.mapdb.DB;
import org.mapdb.DBMaker;
import java.util.concurrent.ConcurrentMap;

DB db = DBMaker.fileDB("data.db").make();
ConcurrentMap<String, String> map = db.hashMap("myMap").createOrOpen();
map.put("key1", "value1");
System.out.println(map.get("key1"));
db.close();

Creates a disk-backed persistent map, adds an entry, retrieves it, and closes the database.

In-memory map

ConcurrentMap<String, Integer> map = DBMaker.memoryDB().make().hashMap("numbers").createOrOpen();
map.put("one", 1);
System.out.println(map.get("one"));

Creates a fast in-memory concurrent map for temporary storage.

Using transactions

DB db = DBMaker.fileDB("data.db").transactionEnable().make();
ConcurrentMap<String, String> map = db.hashMap("myMap").createOrOpen();
map.put("key2", "value2");
db.commit(); // persist changes
db.close();

Enables transactional updates, allowing commit or rollback of changes.

Off-heap storage

DB db = DBMaker.memoryDirectDB().make();
ConcurrentMap<String, String> map = db.hashMap("offHeapMap").createOrOpen();

Stores data off-heap to reduce garbage collection overhead for large datasets.

Queue usage

import org.mapdb.HTreeMap;
HTreeMap<String, String> map = db.hashMap("queueMap").createOrOpen();

MapDB also supports queues and other collection types for concurrent applications.

Error Handling

IllegalArgumentException: Thrown when invalid configuration is provided, such as duplicate map names. Ensure unique names for maps and collections.

DBException: Occurs when disk operations fail. Check file permissions, disk space, and paths.

NullPointerException: Ensure keys and values are not null unless explicitly allowed by collection type.

Best Practices

Always close the DB instance to release file handles.

Use transactions for critical updates to prevent data corruption.

Use off-heap memory for large in-memory datasets to reduce GC overhead.

Regularly back up disk-based databases for safety.

Leverage snapshots for consistent read views in concurrent environments.

Official Docs Github