barrel_db_server (barrel_docdb v1.1.1)
View Sourcebarrel_db_server - Individual database server process
Manages a single database instance. Each database has its own gen_server process that handles all operations for that database. Opens both a document store (regular RocksDB) and an attachment store (RocksDB with BlobDB enabled).
Summary
Functions
Checkpoint both stores into a branch's directories, minting the fork instant inside the writer: every write applied before this call is in the checkpoint and every later one has a larger HLC. Blocks the writer for the memtable flush + hard links.
Delete a document
Delete a local document
Get revisions difference (for replication) Returns {ok, Missing, PossibleAncestors}
Fold over all documents
Fold over all documents with options
Fold over local documents with a given prefix
Get the attachment store reference
Get conflicts for a document Returns list of conflicting revision IDs (excluding the winner)
Get a document When raw_body => true in Opts, returns {ok, CborBin, Meta} for zero-copy responses
Get multiple documents (batch read)
Get a local document
Get the document store reference
Handle synchronous calls
Handle asynchronous casts
Handle other messages The periodic compaction/retention/ttl work runs in a monitored worker so it never blocks the writer loop (a long compaction used to make concurrent writes time out). The periodic timer is re-armed when the worker finishes.
Get database info
Initialize the database server
Acknowledge processed outbox entries by their exact HLC keys. Deleting a key that was already replaced by a newer write is a no-op, so acks never lose work (see barrel_outbox).
Put a document (create or update)
Put multiple documents (batch write)
Put a local document (not replicated)
Put a document with explicit revision history (for replication) Returns {ok, DocId, RevId} on success.
Resolve a conflict by choosing a winning revision or providing a merged doc Resolution can be: - {choose, Rev} - keep this revision as winner, delete other branches - {merge, Doc} - create new revision merging all conflicts
Store a computed embedding as the document's embedding column. CAS on the expected revision: embeddings are derived data, so this never bumps the revision or emits a change; a conflict means a newer write exists (which re-drives the computing indexer anyway).
Start the database server
Stop the database server
Run a retention sweep now. Prunes history entries, superseded version bodies and expired tombstones older than the retention window, then advances the history floor. No-op when retention is infinite (retention_period 0).
Run one doc TTL sweep pass now (test and ops hook). Returns the number of docs tombstoned.
Clean up when terminating
Types
-type att_info() :: #{name := binary(), content_type := binary(), length := non_neg_integer(), digest := binary(), chunked => boolean(), chunk_size => pos_integer(), chunk_count => pos_integer()}.
-type change() :: map().
-type db_name() :: binary().
-type docid() :: binary().
-type revid() :: binary().
-type seq() :: barrel_hlc:timestamp().
-type seq_string() :: binary().
-type view_name() :: binary().
Functions
-spec checkpoint_to(pid(), string(), string()) -> {ok, barrel_hlc:timestamp()} | {error, term()}.
Checkpoint both stores into a branch's directories, minting the fork instant inside the writer: every write applied before this call is in the checkpoint and every later one has a larger HLC. Blocks the writer for the memtable flush + hard links.
Delete a document
Delete a local document
-spec diff_versions(pid(), #{binary() => binary()}) -> {ok, #{binary() => missing | have}} | {error, term()}.
Get revisions difference (for replication) Returns {ok, Missing, PossibleAncestors}
Fold over all documents
Fold over all documents with options
-spec fold_local_docs(pid(), binary(), fun((binary(), map(), term()) -> term()), term()) -> {ok, term()} | {error, term()}.
Fold over local documents with a given prefix
-spec get_att_ref(pid()) -> {ok, barrel_att_store:att_ref()} | {error, term()}.
Get the attachment store reference
Get conflicts for a document Returns list of conflicting revision IDs (excluding the winner)
-spec get_doc(pid(), binary(), map()) -> {ok, map()} | {ok, binary(), map()} | {error, not_found} | {error, term()}.
Get a document When raw_body => true in Opts, returns {ok, CborBin, Meta} for zero-copy responses
Get multiple documents (batch read)
Get a local document
-spec get_store_ref(pid()) -> {ok, barrel_store_rocksdb:db_ref()} | {error, term()}.
Get the document store reference
Handle synchronous calls
Handle asynchronous casts
Handle other messages The periodic compaction/retention/ttl work runs in a monitored worker so it never blocks the writer loop (a long compaction used to make concurrent writes time out). The periodic timer is re-armed when the worker finishes.
Get database info
Initialize the database server
-spec outbox_ack(pid(), barrel_outbox:tag(), [barrel_hlc:timestamp()]) -> ok | {error, term()}.
Acknowledge processed outbox entries by their exact HLC keys. Deleting a key that was already replaced by a newer write is a no-op, so acks never lose work (see barrel_outbox).
Put a document (create or update)
Put multiple documents (batch write)
Put a local document (not replicated)
-spec put_version(pid(), map(), binary(), binary(), boolean()) -> {ok, binary(), binary()} | {error, term()}.
Put a document with explicit revision history (for replication) Returns {ok, DocId, RevId} on success.
-spec resolve_conflict(pid(), binary(), binary(), {choose, binary()} | {merge, map()}) -> {ok, map()} | {error, term()}.
Resolve a conflict by choosing a winning revision or providing a merged doc Resolution can be: - {choose, Rev} - keep this revision as winner, delete other branches - {merge, Doc} - create new revision merging all conflicts
-spec set_doc_embedding(pid(), binary(), binary(), [number()]) -> ok | {error, conflict | not_found | term()}.
Store a computed embedding as the document's embedding column. CAS on the expected revision: embeddings are derived data, so this never bumps the revision or emits a change; a conflict means a newer write exists (which re-drives the computing indexer anyway).
Start the database server
-spec stop(pid()) -> ok.
Stop the database server
Run a retention sweep now. Prunes history entries, superseded version bodies and expired tombstones older than the retention window, then advances the history floor. No-op when retention is infinite (retention_period 0).
-spec sweep_ttl(pid()) -> {ok, non_neg_integer()}.
Run one doc TTL sweep pass now (test and ops hook). Returns the number of docs tombstoned.
Clean up when terminating