Barrel
FR GitHub

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/2 forks the database now. Writes on the branch do not touch the parent until you merge.
  • barrel:doc_versions/2 and barrel:version_body/3 list a document's versions and read each one.
  • barrel:merge/1 writes 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

src/branch_experiment.erl
%% 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.
rebar.config
{erl_opts, [debug_info]}.
{deps, [{barrel, "~> 1.12"}]}.
run.sh
#!/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.

expected.txt

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}

Up and down to moveEnter to open