BergDB runs inside your Java process, keeps every transaction in one append-only stream of files, and lets you read the database as it was at an earlier time.
BergDB has been tested thoroughly, release by release. The API and the stored format will likely change before a stable release. See the status.
Main ideas
- One stream
- The stream is the only durable storage: no write-ahead log and no separate index files. Data, index and history are all records in the stream.
- Self-indexed
- Index nodes are written into the stream lazily, as the writes go on. A start reads only the tail of the stream, so the time to open a database does not grow with its size.
- History
- A read can be made at any time that is still kept, and sees the database as it was then, its indexes included.
- Code only
- Java code is all that is needed, for the advanced features too: a transaction is a Java method, an index is made by a call, and a query is a loop over Java objects. No query language and no schema files.
- Features
- Atomic transactions, written in Java code only. Scans of the keys of a directory and of an index, forward and backward. Secondary indexes on the fields of stored objects, and compound ones, on up to 8 fields. Historic queries with every feature of the queries at the current time.
- Small
- One jar with no dependencies beyond the JDK. No server, few settings.
The Core is a key-value store of byte arrays. The Pub API on top of it stores strings, byte arrays and objects under path-like keys, with secondary indexes.
Status
BergDB has been tested thoroughly, release by release. Whether that is enough for your use is yours to judge: the code, the tests and each release's test results are all in the repository.
How the latest release, 2026.5 (2026-11-13,
tag release-2026.5), was tested on its release commit:
- 1,700 unit tests, 89 functional tests and 26 longer tests, all passed, on macOS with JDK 27 and on Linux with JDK 17 and 27; the unit tests also on an Android emulator.
- A thousand kills of a process in the middle of its writes, each followed by a restart that checks every transaction for lost or changed data; power-loss tests of the stream's files on Linux.
- Fuzz tests of the API and of the index, concurrency tests with jcstress, and Java's index checked, transaction by transaction, against an independent model of the algorithm on generated workloads.
- Programs written against the public API alone, as a user writes them.
- Most of it in one seven-hour run; the release notes, section "Verification", list each step and its result.
No bug is known in 2026.5. The API and the stored format will likely
change before a stable release: a database made by one release may not
open in the next (2026.5 refuses those of 2026.4 and earlier). There is
no upgrade tool; read the data with the old release and put it with the
new one. The main branch moves ahead of the latest
release.
Known issues. No bug is known in release 2026.5. Two things to plan for: the API may change between releases, and the stream format may change between releases.
Get it
- The latest release. Each release's jar and the
Javadoc of its API are on
GitHub Releases,
under the release's tag. The latest is
release-2026.5. - The source.
github.com/bergdb/bergdb.
With a JDK 17 or later and a Unix shell (macOS or Linux),
java/build.shbuilds the jar,java/build/bergdb-release.jar.
Try it
You need a JDK 17 or later and the jar. A first program,
Hello.java:
import bergdb.pub.Connection;
import bergdb.pub.Database;
import bergdb.pub.Factory;
import bergdb.pub.Time;
public class Hello {
public static void main(String[] args) throws Exception {
try (Database db = Factory.database().create("hello-db").start()) {
Connection c = db.connection();
Time first = c.put("/fruit/apple", "red").getTime();
c.put("/fruit/apple", "green");
// prints green
System.out.println(c.get("/fruit/apple", String.class));
// read the past: prints red
c.setLookupTime(first);
System.out.println(c.get("/fruit/apple", String.class));
// wait until durable
c.sync();
}
}
}
Compile and run it with the release's jar beside it:
javac -cp bergdb-2026.5.jar Hello.java
java -cp bergdb-2026.5.jar:. Hello
create opens the database in the directory, or makes a
new one if there is none; open only opens an existing one
and never makes one.
Stored Java objects, a transaction, an index and a query of the
past, in Accounts.java:
import bergdb.pub.*;
public class Accounts {
// a plain Java class
public static class Account {
public String owner;
public long balance;
public Account() {}
public Account(String o, long b) { owner = o; balance = b; }
}
public static void main(String[] args) {
try (Database db = Factory.database().memory().start()) {
Connection c = db.connection();
// a secondary index
db.indexBuilder("by-balance").dir("/acc/")
.type("long").field("balance").start().join();
c.put("/acc/1001", new Account("Ann", 100));
c.put("/acc/1002", new Account("Bob", 20));
c.put("/acc/1003", new Account("Cecilia", 60));
Time before = c.currentTime();
// a transaction: Ann pays Bob 30
c.rw(env -> {
Account from = env.get("/acc/1001", Account.class);
Account to = env.get("/acc/1002", Account.class);
from.balance -= 30;
to.balance += 30;
env.put("/acc/1001", from);
env.put("/acc/1002", to);
});
// in key order
for (Account a : c.usePrimary(Account.class).dir("/acc/")
.objects()) {
System.out.println(a.owner + " " + a.balance);
}
// by balance: 50 or more, largest first
for (Account a : c.useIndex("by-balance", Account.class)
.from(50, true).backward().objects()) {
System.out.println("50 or more: " + a.owner + " " + a.balance);
}
// the same query, in the past
c.setLookupTime(before);
for (Account a : c.useIndex("by-balance", Account.class)
.from(50, true).backward().objects()) {
System.out.println("50 or more, before: " + a.owner + " "
+ a.balance);
}
}
}
}
Compiled and run as Hello, it prints:
Ann 70
Bob 50
Cecilia 60
50 or more: Ann 70
50 or more: Cecilia 60
50 or more: Bob 50
50 or more, before: Ann 100
50 or more, before: Cecilia 60
Account is an ordinary class with public fields and a
public no-argument constructor: a put stores the object, and a get or
a scan gives it back as an Account. rw runs
its action as one atomic transaction: both puts are made, or neither,
and if another transaction changes what the action has read, the
action runs again. memory() gives a database in memory,
gone when it closes; create, as above, keeps one in a
directory.
The API is the packages bergdb.pub and
bergdb.pub.util. The README in
the repository says
what a running database needs and where more examples are.
Links
- Repository: the source, the README and the design documents.
- Releases: each release's jar and Javadoc.
- Issues: bug reports and ideas are welcome.
- Security: how to report a vulnerability. Do not open a public issue for it.
- Licence: the Apache License, Version 2.0.