-
Notifications
You must be signed in to change notification settings - Fork 1
Glossary
What this page covers: the EveryDatabase vocabulary — the terms that recur across the guide, each with a one-paragraph definition and a link to the page that uses it in anger. Skim it when a word on another page is unfamiliar.
📌 Note — definitions are teaching paraphrases. The Javadoc on each type is the precise contract.
The connection/pool lifecycle owner and the factory for repositories. Exposes init / close /
health (all idempotent and async) and repository(EntityDescriptor). A backend instance — SqlStorage,
MongoStorage, LocalFileStorage, etc. — is a Storage. → Architecture Overview
Typed CRUD for one collection: find / findMany / save / saveAll / delete / exists / count /
all, plus the index reads findBy and query. Every method returns a CompletableFuture; there are
no blocking variants. → CRUD Operations
Immutable metadata that tells a backend how to model an entity: the collection name, the key and entity
types, the key extractor, the codec, any index hints, and optional version accessors. Built
with EntityDescriptor.builder(keyType, type)…build() — note keyType comes first. The same descriptor
yields the same cached repository object. → Defining Entities
The named bucket one descriptor maps to — a SQL table, a Mongo collection, a LocalFile directory, an
InMemory map. Its name must match ^[a-zA-Z][a-zA-Z0-9_]*$, the safe intersection across every backend.
→ Entities, Keys & Collections
The identifier of an entity, persisted by its toString() (≤ 255 chars) and matched by value
equals/hashCode. UUID, String, Long, Integer, and records qualify; the default identity
Object.toString() does not. An oversized key is rejected, never truncated. → Entities, Keys & Collections
The serialization strategy for an entity: encode/decode to bytes plus contentType(),
isJsonCodec(), and fileExtension(). JacksonJsonCodec (compact by default, pretty(...) indented)
and JacksonYamlCodec (LocalFile only) are provided. isJsonCodec() is the compatibility seam — SQL,
Mongo, and InMemory require a JSON codec. → Codecs
An optional feature expressed as an extra interface a Storage may implement, rather than a boolean
flag. You check it with instanceof. They are TransactionalStorage (inTransaction(...)),
SchemaAwareStorage (register(...).migrate()), and ChangeFeedStorage (subscribe(...)).
"Capabilities are interfaces, not flags" is the central design idiom. → Architecture Overview
A declaration that a field should be a secondary index, so findBy/query can use it. Declared either
with factories (IndexHint.string / integer / bigInt / decimal / bool / timestamp) or with
@Indexed on the field. Querying an undeclared field throws on every backend. → Indexing & Queries
An opt-in concurrency guard: a long/Long version field that starts at 0 and increments per update;
a save only succeeds if the stored version matches. A mismatch throws OptimisticLockException. Declared
with @OptimisticLock, .versioned(), or .version(getter, setter). Enforced by MySQL/MariaDB,
PostgreSQL, and Mongo; H2/LocalFile/InMemory don't enforce it. → Optimistic Locking
A forward-only schema change applied exactly once, in version order. Backends that implement
SchemaAwareStorage record applied versions in a reserved _schema_migrations table/collection/file.
Base classes: SqlMigration, MongoMigration, LocalFileMigration. → Schema Migrations
A per-context registry mapping each entity type to its manager (RefResolver). There is no global
default — each plugin/subsystem makes its own (new RefRegistry()). It vends the ref-aware
codec(type), the manager(...), and bound ref(...). A Ref resolves only against the registry it's
bound to, so two registries can register a manager for the same type without colliding. A registry can
also chain to a parent (see below) for private-then-shared resolution. → Caching & References
A RefRegistry created as a child of another, with new RefRegistry(parent) (read back via parent()).
resolver(type) — and any Ref resolved through this registry — checks the registry locally first,
then walks up the parent chain, giving private-then-shared resolution: a plugin's own types win, and
types it doesn't register fall back to a shared parent. register(...) / manager(...) are always
local (never touch the parent), so the parent is the single home of cross-plugin shared entities.
isRegistered(type) is local only; isRegisteredInChain(type) walks the chain. → One Entity, Many Databases
A typed pointer to an entity in another collection that serializes as just its key. Resolution is
explicit: peek() (sync, cache-only), resolve() (async, load-on-miss), join() (blocking
convenience). After the first resolve a Ref memoizes the live cell, so later reads are lock-free. A
reference is not a cache. → Typed References (Ref)
A Ref is bound when it carries a RefRegistry (set by the reading codec, or via
refRegistry.ref(key, type) / Ref.of(key, type, refRegistry)) — only then can it resolve. A
Ref.of(key, type, null) is unbound: fine to store (it writes just the key), but resolve() returns a
failed future and peek() throws. → Caching & References
A cache-backed façade over one Repository, owning an identity map (one live instance per key) and
acting as a RefResolver. Methods include resolve/peek, getAll (the N+1 antidote), preloadAll,
saveAndCache, deleteAndEvict, the invalidation knobs, and repository() for the uncached backend.
Registered in a RefRegistry. → Caching Managers
The manager's guarantee that one key maps to one live instance for that instance's lifetime — every
resolve of the same key hands back the same object, so an in-place update is visible to all holders.
This is distinct from the core's stateless repositories, where each find returns a fresh instance. →
Caching Managers
The stable per-key slot inside a manager's cache. Its value is swapped in place on each write/reload,
so a memoized Ref always observes the latest value without re-consulting the store. A cell is live
(holds a value), a tombstone (after a delete), or evicted (removed from the store). →
Caching & References
A monotonic number attached to each cell publication. Writes and reloads are ordered by stamp, so a
slower in-flight reload can neither overwrite a newer saveAndCache nor resurrect a newer
deleteAndEvict. The stamp is what makes concurrent cache updates safe. → Caching & References
The marker a deleted key leaves in the cache (deleteAndEvict), stamp-ordered, so a racy in-flight
reload can't re-install the now-deleted entity. It's cleared by a later re-save (resurrect),
purgeExpired(), or LRU eviction. cachedSize() counts live cells only, not tombstones. → Caching & References
Freshness is a CachePolicy (always() / ttl(Duration) / noCache()), evaluated per read and
per-reference overridable. Capacity is CacheOptions.maxSize (LRU eviction), a store-level property
that can't be set per reference. @RefPolicy(ttlSeconds = …, noCache = …) overrides freshness on a single
Ref field. → Cache Policies & Freshness
The two opt-in forms that make an entity dirty-trackable - cached and mutated in memory, then
persisted later in a batch. Either implement the IDirtyable interface (isDirty() / markClean() /
markDirty()) or annotate a boolean field with @DirtyFlag (pick one, not both). A dirty write-back
cell is always served and never reloaded over — dirty wins — so the in-memory mutation isn't lost to a
stale reload. seedIfAbsent(key, value) caches a not-yet-persisted default with no I/O;
CachingManager.flushDirty() persists the whole dirty set in one batch (e.g. on a periodic tick or
logout). → Caching Managers
The result CachingManager.flushDirty() returns: the per-key outcome of persisting the dirty write-back
set in one batch — what saved, and any failures — so a tick/logout flush can be inspected without throwing
on the first error. → Caching Managers
The optional core capability for cross-process cache invalidation: a backend that can push a
ChangeEvent (collection, key-as-String, op = SAVE/DELETE, version, originId) when an entity
changes, so other instances learn their cached copy is stale. Implemented by Mongo (Change Streams),
PostgreSQL (LISTEN/NOTIFY), and InMemory (local writes). Complementary to the optimistic lock: locking
guards writes, the feed cures read staleness. → Cross-Process Cache Sync
The manager-side single entry point that keeps CachingManager caches fresh across instances. It
subscribes to a backend's change feed where one exists (push) and falls back to version polling
otherwise (pull) — attach(storage) for one backend, auto() for managers spread across several. Routes
each event to the right manager's invalidate/evict. → Cross-Process Cache Sync
The pull counterpart for backends without a push feed (MySQL/MariaDB). On an interval it reads the
current lock_version of each manager's cached keys via Repository.versions(...) and invalidates on
a version bump / evicts on a backend delete. Update detection needs a versioned descriptor (H2/LocalFile
report 0, so polling there catches only deletes). → Cross-Process Cache Sync
The stable identifier of a single ChangeFeedStorage instance, carried on the events it produces.
CacheSync skips an event whose originId matches its own storage (the instance already refreshed its
own cache write-through). Sources that can't attribute origin (Mongo oplog, DB triggers) leave it empty,
and the skip simply never fires. → Cross-Process Cache Sync
One of the two packagings of the same code/API: everydatabase-core (recommended; full deps as
normal POM dependencies) and everydatabase-libby (runtime download via Libby). The
everydatabase-manager add-on is a feature module, not a flavor. → Distribution Flavors
- API Cheat Sheet — the surface these terms name, in one screen.
- Architecture Overview — how Storage / Repository / Descriptor / Codec / capability fit together.
- Caching & References — the manager module that introduces ref / cell / stamp / tombstone.
- Gotchas & Pitfalls · FAQ / Troubleshooting.
EveryDatabase · Home · made by Petrus Pradella
Getting Started
Core Concepts
Working with Data
Backends
Manager Module
- Caching & References
- Typed References (Ref)
- Caching Managers
- Cache Policies & Freshness
- Cross-Process Cache Sync
- One Entity, Many Databases
Operations
Advanced
Reference
Contributing