Branch a database, merge it back, recover a past state.
A branch is a full copy of a database made in constant time. Give one to an agent run or an experiment, review what it did, and merge what survived. Branch at a past instant to read yesterday's data next to today's.
Merging uses the same version vectors as replication: known versions change nothing, edits land, and concurrent edits become conflicts you can see and resolve.
What it is
A fork takes a hard-link checkpoint of the document and attachment stores, so parent and branch share files until either side compacts. The branch is then an ordinary database: reads, writes, queries, the changes feed and replication all work on it, under its own writer id.
- main the parent database
fork: a hard-link checkpoint, O(1)
- exp1 a normal database, its own writer id
merge: only what exp1 changed
- main edits land; concurrent edits become conflicts
Point-in-time recovery
- main history kept for the retention window
branch at T
- yesterday every document as it was at T
read, query, serve
- Next to today’s data main keeps running
What holds, and what tests it
Each property names the test cases that check it.
The branch holds exactly what came before the fork
The fork instant is taken inside the parent’s writer, so a branch made under write load sees every write applied before it and none after.
Checked by fork_under_write_load and fork_isolation in barrel_timeline_SUITE.
A rewind restores state at T
Documents changed after T come back as they were, documents created after T are gone, deletes after T are undone, and indexes and the changes feed match.
Checked by barrel_timeline_pitr_SUITE: rewind_updates, rewind_forgets_created_after_t, rewind_restores_deleted_after_t, rewind_query_index, rewind_feed_replay.
Merging twice changes nothing
A merge ships the branch’s documents as whole states and keeps a checkpoint, so a second merge is a no-op and a later one ships only new work.
Checked by merge_idempotent and merge_incremental in barrel_timeline_merge_SUITE.
Conflicts follow the replication rules
Edits made on both sides become regular conflicts, or are settled by the parent’s conflict_resolver. Attachments and deletes merge too.
Checked by merge_conflict_lww, merge_conflict_merger, merge_attachments, merge_delete.
Search works on the branch right away
A record-mode branch rebuilds its vector store from the embeddings stored in the documents, with no embedder calls. After a merge, the parent re-indexes what changed.
Checked by barrel_record_timeline_SUITE: backfill_stored_vectors_no_embed_calls, merge_reindexes_parent.
Outside the window, a clean refusal
A T below the history floor fails with pitr_window_exceeded and leaves nothing behind.
Checked by rewind_floor_guard in barrel_timeline_pitr_SUITE.
Use it
Branch, edit, merge
{ok, _} = barrel_docdb:branch_db(<<"main">>, <<"exp1">>, #{}),
%% the branch is a normal database; edits stay on it
{ok, D} = barrel_docdb:get_doc(<<"exp1">>, <<"a">>),
{ok, _} = barrel_docdb:put_doc(<<"exp1">>, D#{<<"v">> => 2}),
%% ship the branch's edits back; rerun any time
{ok, #{docs_written := 1}} =
barrel_docdb:merge_branch(<<"exp1">>, #{}),
ok = barrel_docdb:delete_db(<<"exp1">>). curl -X POST localhost:8080/db/main/_timeline/branch \
-H 'content-type: application/json' -d '{"name":"exp1"}'
curl localhost:8080/db/main/_timeline
# called on the branch
curl -X POST localhost:8080/db/exp1/_timeline/merge
curl -X DELETE 'localhost:8080/db/exp1?purge=true' {"jsonrpc":"2.0","id":7,"method":"tools/call",
"params":{"name":"branch_create",
"arguments":{"db":"main","name":"exp1"}}}
{"jsonrpc":"2.0","id":8,"method":"tools/call",
"params":{"name":"merge","arguments":{"db":"exp1"}}} Branch at a past instant
Every document changed after T is restored to its last state at or before T, including conflicts that were open at that instant.
{ok, _Changes, T} = barrel_docdb:get_changes(<<"main">>, first),
%% ... more writes happen ...
{ok, _} = barrel_docdb:branch_db(<<"main">>, <<"yesterday">>,
#{at => T}). curl -X POST localhost:8080/db/main/_timeline/branch \
-H 'content-type: application/json' \
-d '{"name":"yesterday","at_time":"2026-11-07T09:00:00Z"}' {"jsonrpc":"2.0","id":9,"method":"tools/call",
"params":{"name":"branch_create","arguments":{
"db":"main","name":"yesterday","at":"<changes cursor>"}}} A record-mode branch, from a recorded run
The branch gets a fresh vector store, filled from the stored embeddings, so search answers before the first edit.
{ok, Br} = barrel:branch(Db, <<"support_draft">>,
#{vectordb => #{db_path => "data/support_draft_vec"}}),
barrel:search(Br, <<"export billing CSV">>, #{k => 1}),
{ok, Bd} = barrel:get_doc(Br, <<"kb:201">>),
{ok, _} = barrel:put_doc(Br,
Bd#{<<"title">> => <<"Export invoices and credit notes">>}),
barrel:merge(Br). {ok,[#{... key => <<"kb:201">>,score => 0.5059366870734147}]}
{ok,#{failed => [], docs_read => 1, docs_written => 1,
doc_write_failures => 0, ...}} One level of branches
barrel_docdb:branch_db(<<"edge_a_review">>, <<"nested">>, #{}). {error,cannot_branch_a_branch} Limits
- Lineage is linear: a branch of a branch is refused with
cannot_branch_a_branch. Cross-lineage merges are planned. - The rewind window is the retention window:
retention_period, 30 days by default. Below the history floor, a branch at T fails withpitr_window_exceeded. - A branch made at a past instant keeps the attachments as they were at the fork, not at T: attachments have no history.
- There is no per-merge conflict policy; the parent’s
conflict_resolverapplies, and the merge report carries counts, not per-document conflict detail. - A plain
barrelbranch starts with an empty vector store: vectors you added withvector_addare not carried. Re-add them, or use record mode. - “Revert the parent to T” is not an operation yet; a rewind is a new branch next to the parent.
- Runtime settings (channels,
conflict_resolver, retention, encryption) must be passed again when you reopen a branch, as for any database. A branch that is not open is not listed. - Over REST and MCP, branching and merging need a server credential: capability tokens get 403 on the
_timelineroutes.