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/2withvectordb => none: documents only, no vector store.barrel:put_docs/2returns one result per document, each with its revision.- An update must carry the
_revit read; a stale_revreturns{error, conflict}. - BQL with
WHERE,ORDER BY, a$parameter,INon an array andUNNEST. 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
%% 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. {erl_opts, [debug_info]}.
{deps, [{barrel, "~> 1.12"}]}. %% 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}}}]}]}]. #!/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.
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