barrel_db_server (barrel_docdb v1.0.0)
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
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
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