-
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. The two are TransactionalStorage (inTransaction(...)) and
SchemaAwareStorage (register(...).migrate()). "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. → Caching & References
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
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