Embedded model - NetlyDB documentation

A database inside your process

A client-server database runs as its own process, usually on its own machine, and your application talks to it over the network. NetlyDB is a library: the engine runs in your application's process and your code calls it through ordinary method calls. There is no server to install, patch, secure or keep running separately, and no connection string.

The trade-off is that the database shares its host's lifetime and resources. It starts and stops with your application, uses your process's memory, and is reachable from other processes only through the optional modules you choose to enable.

One process. Your code calls the engine directly; the engine keeps each collection in memory and commits every change to the local disk before confirming it.

Data lives in memory, changes live on disk

Each collection is held in memory as a set of shards (ShardCount, default 4 - an in-process partitioning, not a distribution across machines). Every change is first committed to that collection's write-ahead log on disk; periodically the collection is written out as a snapshot. At startup each collection is rebuilt from its last snapshot and the log that follows it.

The consequence: reads never wait on disk, and the data you can hold is bounded by the memory you give the process. Data sets larger than memory, and paging from disk, are not goals of the current releases. Startup time grows with the amount of data and the size of vector indexes that have to be rebuilt.

One database per process, one owner per store

One database per process is the supported configuration, and it is enforced: a second store in one container throws instead of silently sharing state.
One writable owner per store. A store directory is owned exclusively by the process that opened it for writing. A second process cannot open the same store writable.
An explicit lifecycle. The engine moves through defined states - Starting, Recovering, Ready, Degraded, RecoveryRequired, ShuttingDown, Stopped - and admits reads and writes only in states that allow them. Health probes report the same states; see Health & metrics.

The engine's lifecycle states. Startup recovers before the engine is ready; ambiguity recovery cannot resolve stops writable startup; a degradation is reported rather than hidden.

Memory limits

Memory limits are off by default. When enabled with options.Memory.EnableMemoryLimits, each collection can be limited by document count or by estimated size, with one of two policies:

Reject (default): an add that would exceed the limit throws NetlyDBQuotaExceededException. Updates and deletes still succeed. Nothing is lost.
EvictLeastRecentlyUsed: least-recently-used documents are deleted - a real, logged delete - until the collection is back under its limit. This is cache behaviour, for collections that front another store of record.

Growing beyond one process

The same engine can be extended without replacing it: a REST API, a Management UI and an MCP server run as hosted modules inside the same process, and several nodes can replicate to each other. See Deployment models.