Glossary

Terms used throughout the MemDb documentation.

Access mode — The AccessMode value passed to SetMode during configuration, controlling which operations a database supports. Three values are defined: ReadWrite (default), ReadOnly, and AppendOnly. A database configured without a directory path is implicitly a volatile dataset — an independent property from access mode. See Core Concepts — Modes.

AppendOnly — An AccessMode that supports Insert and unfiltered Count() only. No in-memory cache is maintained; writes go straight through the queue to disk. The fastest write path.

Applied index — A user-defined index over any property whose type implements IComparable. Maintained automatically on insert, update, and delete. Held in RAM only; rebuilt on each open. Multiple records may share the same indexed value. See Indexes — Applied Indexes.

Archive — The optional zip file (htl.{datasetName}.zip) that accumulates stale and deleted record file sets each time Defrag runs against a database configured with ArchiveOnDefrag. Combined with the live data files, the archive enables point-in-time restore.

Cache — The in-memory representation of the dataset. Held as a List<MemDbRecord<T>> indexed by cache position. The authoritative source for reads in ReadWrite and ReadOnly modes.

Cache boundary — The conceptual line between caller-owned objects and the cache’s internal record storage. MemDb deep-clones every record that crosses this boundary in either direction. See Data Integrity.

Cloner — An IMemDbCloner<T> implementation that deep-copies records at the cache boundary. The default cloner round-trips each record through the configured serializer; a custom cloner that copies fields directly is typically much faster. See Extensibility — Custom Cloning.

Configuration — The set of options registered against a dataset name via MemDb.ConfigureFor<T>(name, path).Register(). Includes the access mode, serializer, cloner, encryption key, indexes, flush interval, snapshot and archive directories. Configuration is held in-process only and must be re-registered on every application start. See Getting Started — Configuration.

Data file — htl.{datasetName}.db, the append-only file holding serialized record bytes. Paired with the Map file. See Core Concepts — Persistence.

Dataset — A named, independently managed collection of records of a single type T. Each dataset has its own files, its own cache, and its own lock. Identified by a unique string name passed to ConfigureFor and Open.

Defragmentation — The offline process of compacting the data file by removing stale and deleted records. Invoked via MemDb.Defrag(datasetName) while the database is closed. See Maintenance — Defragmentation.

Deleted (record state) — A record that has been explicitly deleted via Delete. Excluded from reads. Reclaimable by PurgeCache (RAM) and Defrag (disk).

Encryption flag — A one-byte field on each pointer in the .map file indicating whether the corresponding record bytes in the .db file are AES-encrypted. Set at insert time and preserved across updates. See Encryption.

Encryption key — The 256-bit AES key used to encrypt and decrypt records flagged as encrypted. Provided at configuration time either directly via EncryptWithKey(() => bytes) or derived from a password via EncryptWithPassword(() => password). See Encryption — Configuration.

Flush — The act of writing pending records and pointer-state changes from the persister’s queues to the on-disk .db and .map files. Triggered by the flush timer, by explicit db.Flush(), or on dispose.

Fresh (record state) — The current authoritative version of a record. Reads return only fresh records.

Identity index — An optional in-memory dictionary mapping each record’s identity key to its cache position, enabling O(1) by-id lookups. Disabled by default; enabled via IndexOnIdentity(true).

Identity key — The auto-incremented long id assigned by MemDb to each record on insert. Unique within a dataset.

Lock file — ~$htl.{datasetName}.lock, an OS-enforced cross-process lock created when a database is opened and removed automatically when the holding process exits.

Log-structured — A storage layout where new versions of records are appended rather than written in place. Stale and deleted versions remain on disk until reclaimed by purge or defrag. Enables crash safety and historical archival at the cost of periodic compaction.

Map file — htl.{datasetName}.map, the pointer map paired with the Data file. Contains a 12-byte header followed by one 39-byte pointer per record (id, state, timestamps, encryption flag, position, length). See Core Concepts — Persistence.

MemDb instance — A MemDb<T> object obtained from MemDb.Open<T>(datasetName). The handle through which all read and write operations are issued. Implements IDisposable.

Persister — The internal component that flushes the cache’s pending writes to disk. Owns the insert and state-modification queues, the flush timer, the file handles, and the encryptor.

Pointer — A 39-byte record in the .map file describing a single entry in the .db file: id, state, timestamps, encryption flag, position, and length.

Purge — Reclaiming RAM occupied by stale and deleted records in the cache, without closing the database. Invoked via db.PurgeCache().

ReadOnly — An AccessMode that disallows Insert, Update, and Delete. The full dataset is loaded into RAM on open. Reads behave identically to ReadWrite.

ReadWrite — The default AccessMode. Full read and write access; the entire dataset is held in RAM and all modifications are persisted to disk.

Record — A single application-level object stored in a dataset. Wrapped internally in a MemDbRecord<T> carrying state and timestamps.

Restore — Producing a new copy of a database at a chosen historical UTC timestamp from the live files combined with the archive zip. Requires ArchiveOnDefrag to have been configured. Invoked via MemDb.Restore. See Point-in-Time Restore.

Serializer — An IMemDbSerializer<T> implementation that converts records to and from bytes for disk storage. The default is a configured System.Text.Json round-trip.

Snapshot — An online point-in-time backup written to a configured snapshot directory. The source database remains fully operational. The snapshot is a fully independent database that can be opened in any mode. See Snapshots.

Stale (record state) — A record superseded by a later update. Excluded from reads. Reclaimable by PurgeCache (RAM) and Defrag (disk).

Volatile dataset — A dataset configured without a directory path. Held entirely in RAM for the lifetime of the process; no files are created. Useful for test fixtures and ephemeral caches.