barrel_dbs (barrel v1.0.0)
View SourceComposed database lifecycle manager.
Owns open barrel database handles for callers that need a long-lived owner (a barrel database links its vector store to the process that opens it): the REST server and the agent layer ask this manager for handles instead of opening databases themselves. Databases opened directly through barrel:open/2 are not tracked here and keep their caller-owned lifecycle.
The manager makes hundreds of ephemeral databases practical: handles open lazily, every use touches them, a sweep closes entries idle past dbs_idle_timeout, and dbs_max_open bounds the open set with LRU eviction of idle entries (pinned entries are never closed automatically). All knobs live in the barrel application env and are read at use, so they can change at runtime:
dbs_idle_timeout- ms of idleness before the sweep closes a db (default 300000; 0 disables idle closing)dbs_max_open- max open dbs, 0 = unlimited (default 0); at the cap the least recently used unpinned entry idle for at leastdbs_evict_guardms is evicted, else the open fails with{error, too_many_open_dbs}dbs_evict_guard- minimum idleness for eviction, shrinking the race between handing out a handle and closing its db (default 5000 ms)
The manager does not trap exits: if an owned store crashes, the manager crashes with it, the supervisor restarts it with an empty cache, and databases reopen on the next ensure.
Summary
Functions
Fork Parent into BranchName and own the branch handle. Opts are barrel:branch/3 options; open_opts inside them is used to open the parent when it is not already open.
Close and forget the database Name. Idempotent.
Close every entry tagged with Owner (a subsystem shutting down closes exactly what it opened, pinned or not).
Destroy the database Name: close it and delete its files (docdb and vector store).
Return the (possibly newly opened) handle for Name and touch its last-used time.
Like ensure/1 with open options for a first open (a cached handle is returned as-is; runtime config such as encryption must match what the db was opened with). The extra owner => Term option tags the entry for close_owned/1 and is not passed to barrel:open/2.
Names of the databases this manager holds open.
Exempt an open database from idle closing and eviction (system registries, continuous replication holders).
Run one idle sweep synchronously (test hook; the periodic timer calls the same code).
Undo pin/1.
Functions
-spec branch(barrel:db_name(), barrel:db_name(), map()) -> {ok, barrel:db()} | {error, term()}.
Fork Parent into BranchName and own the branch handle. Opts are barrel:branch/3 options; open_opts inside them is used to open the parent when it is not already open.
-spec close(barrel:db_name()) -> ok.
Close and forget the database Name. Idempotent.
-spec close_owned(term()) -> ok.
Close every entry tagged with Owner (a subsystem shutting down closes exactly what it opened, pinned or not).
-spec destroy(barrel:db_name()) -> ok | {error, term()}.
Destroy the database Name: close it and delete its files (docdb and vector store).
-spec ensure(barrel:db_name()) -> {ok, barrel:db()} | {error, term()}.
Return the (possibly newly opened) handle for Name and touch its last-used time.
-spec ensure(barrel:db_name(), map()) -> {ok, barrel:db()} | {error, term()}.
Like ensure/1 with open options for a first open (a cached handle is returned as-is; runtime config such as encryption must match what the db was opened with). The extra owner => Term option tags the entry for close_owned/1 and is not passed to barrel:open/2.
-spec list() -> [binary()].
Names of the databases this manager holds open.
-spec pin(barrel:db_name()) -> ok | {error, not_open}.
Exempt an open database from idle closing and eviction (system registries, continuous replication holders).
-spec sweep() -> ok.
Run one idle sweep synchronously (test hook; the periodic timer calls the same code).
-spec unpin(barrel:db_name()) -> ok | {error, not_open}.
Undo pin/1.