Barrel
FR GitHub

Embed barrel in an Erlang app

This project runs barrel inside your own Erlang node: it opens a database, writes three documents, updates one, queries them with BQL, closes the database and reopens it to read the data back from disk. There is no server and no network. Start here when your application runs on the BEAM and owns its data.

Prerequisites

  • Erlang/OTP 26 or later (this run used OTP 29) and rebar3.
  • A C compiler and CMake: rocksdb and the vector store build their native code on the first compile, which takes a few minutes.

Run

./run.sh

run.sh compiles the project (rebar3 compile, dependencies from Hex), deletes ./data, then runs embedded_erlang:main/0 in a fresh node with erl -noshell -config config/sys. config/sys.config puts the data under ./data/docdb and sends logs to stderr.

To use barrel in your own app, add the dependency and list barrel in the applications of your .app.src:

{deps, [{barrel, "~> 1.12"}]}.

What it shows

  • barrel:open/2 with vectordb => none: documents only, no vector store.
  • barrel:put_docs/2 returns one result per document, each with its revision.
  • An update must carry the _rev it read; a stale _rev returns {error, conflict}.
  • BQL with WHERE, ORDER BY, a $parameter, IN on an array and UNNEST.
  • barrel:close/1, then a reopen that reads the same data.

Expected output

Each step prints one line or a list of rows. The output of a real run is in expected.txt; revisions differ on every run.

Download The folder on GitHub, with every file below.

Source

src/embedded_erlang.erl
%% Barrel embedded in an Erlang node: open a database, write
%% documents, query them with BQL, close cleanly. No server.
-module(embedded_erlang).
-export([main/0]).

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),

    %% A documents-only database: no vector store.
    {ok, Db} = barrel:open(<<"tasks">>, #{vectordb => none}),
    io:format("opened ~s~n", [maps:get(name, Db)]),

    Tasks = [
        #{<<"id">> => <<"task:1">>, <<"title">> => <<"Write notes">>,
          <<"status">> => <<"open">>, <<"priority">> => 2,
          <<"tags">> => [<<"docs">>]},
        #{<<"id">> => <<"task:2">>, <<"title">> => <<"Fix login">>,
          <<"status">> => <<"open">>, <<"priority">> => 3,
          <<"tags">> => [<<"bug">>, <<"auth">>]},
        #{<<"id">> => <<"task:3">>, <<"title">> => <<"Ship 1.0">>,
          <<"status">> => <<"done">>, <<"priority">> => 1,
          <<"tags">> => [<<"release">>]}
    ],
    Results = barrel:put_docs(Db, Tasks),
    [io:format("put ~s rev ~s~n", [Id, Rev])
     || {ok, #{<<"id">> := Id, <<"rev">> := Rev}} <- Results],

    %% Read one back; the current version comes with _rev.
    {ok, T2} = barrel:get_doc(Db, <<"task:2">>),
    io:format("get task:2 -> ~s~n", [maps:get(<<"title">>, T2)]),

    %% BQL: filter and sort.
    show(barrel:query(Db,
        <<"SELECT title, priority FROM tasks "
          "WHERE status = 'open' ORDER BY priority DESC">>)),

    %% An update carries the _rev it read.
    {ok, _} = barrel:put_doc(Db, T2#{<<"status">> => <<"done">>}),
    io:format("update task:2 -> done~n"),

    %% Writing again with the old _rev is refused.
    Stale = barrel:put_doc(Db, T2#{<<"title">> => <<"Stale">>}),
    io:format("stale write -> ~p~n", [Stale]),

    %% Membership in an array, and a parameter.
    show(barrel:query(Db,
        <<"SELECT id, title FROM tasks "
          "WHERE 'bug' IN tags AND status = $s">>,
        #{params => #{<<"s">> => <<"done">>}})),

    %% One row per array element.
    show(barrel:query(Db,
        <<"SELECT k.id, t AS tag FROM tasks AS k, "
          "UNNEST(k.tags) AS t ORDER BY t">>)),

    %% Close, reopen: the data is on disk.
    ok = barrel:close(Db),
    {ok, Db2} = barrel:open(<<"tasks">>, #{vectordb => none}),
    {ok, Rows, _} = barrel:query(Db2,
        <<"SELECT id, status FROM tasks ORDER BY id">>),
    io:format("after reopen: ~p~n", [Rows]),
    ok = barrel:close(Db2),
    ok = application:stop(barrel),
    io:format("closed~n"),
    ok.

show({ok, Rows, _Meta}) ->
    io:format("rows: ~b~n", [length(Rows)]),
    [io:format("  ~p~n", [R]) || R <- Rows],
    ok.
rebar.config
{erl_opts, [debug_info]}.
{deps, [{barrel, "~> 1.12"}]}.
config/sys.config
%% Data under ./data, logs on stderr so stdout is the example output.
[{barrel_docdb, [{data_dir, "data/docdb"}]},
 {kernel, [{logger_level, warning},
           {logger, [{handler, default, logger_std_h,
                      #{config => #{type => standard_error}}}]}]}].
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 'embedded_erlang: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
opened tasks
put task:1 rev 000001a1ba494ab900000000@w76a5b31a6f8fceb7
put task:2 rev 000001a1ba494ac200000000@w76a5b31a6f8fceb7
put task:3 rev 000001a1ba494ac200000001@w76a5b31a6f8fceb7
get task:2 -> Fix login
rows: 2
  #{<<"id">> => <<"task:2">>,<<"priority">> => 3,
    <<"title">> => <<"Fix login">>}
  #{<<"id">> => <<"task:1">>,<<"priority">> => 2,
    <<"title">> => <<"Write notes">>}
update task:2 -> done
stale write -> {error,conflict}
rows: 1
  #{<<"id">> => <<"task:2">>,<<"title">> => <<"Fix login">>}
rows: 4
  #{<<"id">> => <<"task:2">>,<<"tag">> => <<"auth">>}
  #{<<"id">> => <<"task:2">>,<<"tag">> => <<"bug">>}
  #{<<"id">> => <<"task:1">>,<<"tag">> => <<"docs">>}
  #{<<"id">> => <<"task:3">>,<<"tag">> => <<"release">>}
after reopen: [#{<<"id">> => <<"task:1">>,<<"status">> => <<"open">>},
               #{<<"id">> => <<"task:2">>,<<"status">> => <<"done">>},
               #{<<"id">> => <<"task:3">>,<<"status">> => <<"done">>}]
closed

Up and down to moveEnter to open