Home

EveryDatabase

One async API. Every database. Zero lock-in.

A backend-agnostic persistence layer for the JVM. Write your data-access code once against a small, typed, CompletableFuture-based API — then run it on MySQL/MariaDB, PostgreSQL, H2, MongoDB, local files, grouped files, or in-memory without changing a line. Migrate data between any two of them with a single builder.

This wiki is the developer guide.

---

Start here

1. Installation — pick a distribution flavor and add one dependency.
2. Quick Start — descriptor → storage → save/find, end to end.
3. Defining Entities — model your data with EntityDescriptor.
4. Architecture Overview — the five types you actually code against.

What can it do?

You want to…	Go to
Read & write entities	CRUD Operations
Secondary-index & query fields	Indexing & Queries
Guard against concurrent writers	Optimistic Locking
Run atomic units of work	Transactions
Evolve a collection's structure (DDL)	Schema Migrations
Upcast entity payloads written by an older build	Payload Schema Evolution
Pick the right engine	Choosing a Backend
Cache hot data & reference entities across collections/databases	Caching & References
Keep those caches fresh across many instances	Cross-Process Cache Sync
Mutate in memory & flush later, resolving conflicts	Write-Back & Conflict Resolution
Move data between backends	Moving Data Between Backends
See what the library is logging	Logging & Diagnostics

Pick a backend

Seven backends, one API. Full matrix on Choosing a Backend; the short version:

Backend	Good for	Transactions	Migrations	Indexes	Optimistic locking
MySQL / MariaDB	production, shared DB	✅	✅	✅	✅
PostgreSQL	production, shared DB	✅	✅	✅	✅
H2	embedded / dev	✅	✅	✅	❌
MongoDB	document workloads	✅¹	✅	✅	✅
Local files	tiny deploys, human-readable	❌	✅	⚠️ scan	❌
Grouped files	key-major aggregate files	❌	✅	⚠️ scan	❌
In-memory	tests / CI	✅²	✅	✅	❌

_{¹ replica set required · ² no isolation}

The manager add-on

The optional everydatabase-manager module adds typed references (Ref<K, V>) and per-type caching in front of the core — including the flagship One Entity, Many Databases pattern, where one entity fans out across MySQL, Postgres, Mongo, H2, files and memory at once.

Reference & help

• Dependency Versions & Overrides — versions, Java floors, override recipes.
• Gotchas & Pitfalls — the traps worth knowing before you hit them.
• FAQ — common errors → cause → fix.
• Glossary — descriptor, codec, cell, tombstone, capability…

📌 Note — this wiki is a separate git repository (gitignored by the main repo). To contribute, see Editing this Wiki.