rocksdbffm is an experimental Java wrapper for RocksDB built on the Foreign Function & Memory (FFM) API, targeting JDK 25+.
It aims to be a more maintainable alternative to the JNI-based rocksdbjni: mappings are plain Java
against rocksdb/c.h, so new RocksDB features need no C++ glue. Reads are roughly 2× faster than
JNI — see docs/benchmarks.md for the numbers and their caveats, and
docs/explanation.md for why.
AI-assisted development: This project uses Claude Code heavily for implementation work — C header mapping, test generation, and documentation. Architecture, API design, and all decisions are human-driven.
Import the BOM, then depend on rocksdbffm-core plus one native artifact per platform you ship to
(full classifier list in docs/reference.md#artifacts):
<dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.dfa1</groupId>
<artifactId>rocksdbffm-bom</artifactId>
<version>0.8</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
<dependencies>
<dependency>
<groupId>io.github.dfa1</groupId>
<artifactId>rocksdbffm-core</artifactId>
</dependency>
<dependency>
<groupId>io.github.dfa1</groupId>
<artifactId>rocksdbffm-native-osx-aarch64</artifactId>
<scope>runtime</scope>
</dependency>
</dependencies>try (var db = RocksDB.openReadWrite(Path.of("/tmp/demo-db"))) {
db.put("user:1".getBytes(), "alice".getBytes());
byte[] value = db.get("user:1".getBytes()); // null if absent
db.delete("user:1".getBytes());
}Run with --enable-native-access=ALL-UNNAMED. Step-by-step setup — including batches, iterators, and
options — is in the tutorial.
Docs follow the Diátaxis framework.
| Document | Mode | Contents |
|---|---|---|
| docs/tutorial.md | Tutorial | Start to finish: project setup, open a DB, put/get/delete, batch, iterate |
| docs/how-to.md | How-to | Recipes: column families, snapshots, transactions, backups, TTL, WAL tailing, … |
| docs/reference.md | Reference | Artifacts, API surface by area, options, enums, feature status |
| docs/explanation.md | Explanation | Why FFM over JNI, ownership model, domain types, native library loading |
| docs/benchmarks.md | Explanation | FFM vs JNI throughput, methodology, how to reproduce |
| docs/c-api-gaps.md | Reference | What rocksdb/c.h exposes but is unwrapped, and what needs an upstream PR |
| docs/adr/ | Explanation | Architecture Decision Records — why a significant decision was made, at the time |
Requirements: JDK 25+, Zig 0.15.x, and — for the Windows native builds
only — CMake plus make or Ninja.
git submodule update --init --recursive # clone the rocksdb submodule (first time)
./mvnw generate-resources -Pnative-build # build the native library (first time or after clean)
./mvnw testNever run ./mvnw install — it pollutes ~/.m2 with local artifacts. Use compile, test, or
package.
./mvnw --batch-mode release:clean release:prepare
git push && git push --tagsGitHub Actions picks up the tag and deploys to Maven Central.
Licensed under the same terms as RocksDB (LevelDB/Apache 2.0).