Branch, compare, merge, recover
This project tries a change on a branch of a database before it touches the original. It writes a small price list, raises one price on the main database, branches it, edits, adds and deletes on the branch, compares the two with the same BQL query and the version history, merges the branch back, then opens a second branch of the main database as it was before any change (point-in-time recovery). Use it when an agent run, a migration or a bulk edit needs review before it lands.
Prerequisites
- Erlang/OTP 26 or later (this run used OTP 29) and rebar3.
- A C compiler and CMake for the native dependencies (first compile takes a few minutes).
Run
./run.sh
run.sh compiles the project, deletes ./data, then runs
branch_experiment:main/0 once.
What it shows
barrel:changes(Db, first)returns the cursor of the latest change: keep it to come back to that point later.barrel:branch/2forks the database now. Writes on the branch do not touch the parent until you merge.barrel:doc_versions/2andbarrel:version_body/3list a document's versions and read each one.barrel:merge/1writes the branch's edits into the parent and returns a report.barrel:branch(Db, Name, #{at => Cursor})opens a branch of the past.- A branch of a branch is refused:
{error, cannot_branch_a_branch}.
Notes
- Lineage is one level deep, and a point in time older than the
retained history fails with
pitr_window_exceeded(the default retention is 30 days). - This database has no vector store. On a record-mode database a branch rebuilds its index from the stored embeddings; a plain database's branch carries no vectors.
Expected output
The price table at each step, the versions of one document and the
merge report. The output of a real run is in expected.txt.
Download The folder on GitHub, with every file below.
Source
%% Try a change on a branch, compare it with the parent, merge it,
%% then open a branch of the past (point-in-time recovery).
-module(branch_experiment).
-export([main/0]).
-define(Q, <<"SELECT id, price FROM plans ORDER BY id">>).
main() ->
try run() of
ok -> halt(0)
catch C:R:S ->
io:format(standard_error, "~p:~p~n~p~n", [C, R, S]),
halt(1)
end.
run() ->
{ok, _} = application:ensure_all_started(barrel),
{ok, Db} = barrel:open(<<"pricing">>, #{vectordb => none}),
_ = barrel:put_docs(Db, [plan(<<"free">>, 0),
plan(<<"pro">>, 20),
plan(<<"team">>, 50)]),
%% The changes cursor after the first writes: a point in time.
{ok, _, T1} = barrel:changes(Db, first),
table("main, initial", Db),
%% Later, on main: pro goes up.
ok = set_price(Db, <<"plan:pro">>, 25),
table("main, pro raised to 25", Db),
%% A branch shares the parent's history up to now.
{ok, Exp} = barrel:branch(Db, <<"pricing_exp">>),
ok = set_price(Exp, <<"plan:team">>, 45),
{ok, _} = barrel:put_doc(Exp, plan(<<"edu">>, 5)),
{ok, Free} = barrel:get_doc(Exp, <<"plan:free">>),
{ok, _} = barrel:delete_doc(Exp, <<"plan:free">>,
#{rev => maps:get(<<"_rev">>, Free)}),
io:format("~nbranches of pricing: ~p~n",
[barrel_docdb:list_branches(<<"pricing">>)]),
%% Compare: the same query on both sides.
table("branch", Exp),
table("main, unchanged", Db),
{ok, Versions} = barrel:doc_versions(Exp, <<"plan:team">>),
io:format("~nplan:team versions on the branch:~n"),
[begin
{ok, B} = barrel:version_body(Exp, <<"plan:team">>, V),
io:format(" ~s price ~p~n", [S, maps:get(<<"price">>, B)])
end || #{status := S, version := V} <- Versions],
%% Merge the branch back into main.
{ok, Report} = barrel:merge(Exp),
io:format("~nmerge: ~kp~n",
[maps:with([docs_read, docs_written, failed], Report)]),
table("main, after merge", Db),
%% Point-in-time: a branch of main as it was at T1.
{ok, Past} = barrel:branch(Db, <<"pricing_t1">>, #{at => T1}),
table("branch at the first cursor", Past),
%% Branches are one level deep.
io:format("~nbranch of a branch: ~p~n",
[barrel:branch(Exp, <<"nested">>)]),
ok = barrel:delete(Exp),
ok = barrel:delete(Past),
ok = barrel:close(Db),
ok.
plan(Name, Price) ->
#{<<"id">> => <<"plan:", Name/binary>>, <<"type">> => <<"plan">>,
<<"price">> => Price}.
set_price(Db, Id, Price) ->
{ok, Doc} = barrel:get_doc(Db, Id),
{ok, _} = barrel:put_doc(Db, Doc#{<<"price">> => Price}),
ok.
table(Title, Db) ->
{ok, Rows, _} = barrel:query(Db, ?Q),
io:format("~n~s:~n", [Title]),
[io:format(" ~-10s ~p~n", [Id, P])
|| #{<<"id">> := Id, <<"price">> := P} <- Rows],
ok. {erl_opts, [debug_info]}.
{deps, [{barrel, "~> 1.12"}]}. #!/bin/sh
# Build, then run main/0 once on a fresh data directory.
set -e
cd "$(dirname "$0")"
rebar3 compile >&2
rm -rf data
exec erl -noshell -config config/sys \
-pa _build/default/lib/*/ebin _build/default/checkouts/*/ebin \
-eval 'branch_experiment:main()' Expected output
The expected.txt of the example, from a real run. Revisions, ids, tokens and timestamps differ on every run; scripts/verify-examples.sh masks them before it compares.
main, initial:
plan:free 0
plan:pro 20
plan:team 50
main, pro raised to 25:
plan:free 0
plan:pro 25
plan:team 50
branches of pricing: [<<"pricing_exp">>]
branch:
plan:edu 5
plan:pro 25
plan:team 45
main, unchanged:
plan:free 0
plan:pro 25
plan:team 50
plan:team versions on the branch:
current price 45
superseded price 50
merge: #{docs_read => 3,docs_written => 3,failed => []}
main, after merge:
plan:edu 5
plan:pro 25
plan:team 45
branch at the first cursor:
plan:free 0
plan:pro 20
plan:team 50
branch of a branch: {error,cannot_branch_a_branch}