Barrel
FR GitHub

Write on every copy.

Every Barrel database takes writes: on a server, on an edge node, in a browser. Replication keeps the copies in agreement. They pick the same winner everywhere, keep every concurrent edit until you resolve it, and resume where they stopped after a crash.

No leader, no primary, no quorum to wait for. Each copy works on its own and catches up when it can reach the others.

Set up replicationRead the proofs

Two sites edit the same task

Cut the link, edit on both sides, sync. Neither edit is lost: both copies pick the same winner and keep the other edit as a conflict until someone resolves it.

The call behind your last stepDemonstration in your browser, following barrel's rules

 

What it guarantees, and how we check

Each property names what tests it. The proofs and the end-to-end scripts are in the repository; you can run them yourself.

Every copy agrees

Copies converge to the same winner, body and deletion state for every document, whatever order the writes arrive in.

Checked by a TLA+ model of three replicas with crashes, Lean proofs of the merge laws, and the three-peer active-active script.

No write is lost

A write replaces only the versions it read. Concurrent edits stay side by side as conflicts until someone resolves them.

Checked by an Ivy proof for any number of replicas and writers, and the active-active script (nine edits over the winner, the losing write stays).

Safe to retry

Delivery is idempotent, so a batch sent twice changes nothing. Checkpoints after each batch let a run resume where it stopped.

Checked by the crash script, which kills the target mid-batch and then the peer running the task.

Survives power cuts

Writes made with sync => true survive a power loss. A copy that loses a batch it had acknowledged gets it again on the next run.

Checked by the power-fail script on LazyFS, which drops every write that was not flushed to disk.

Files travel with documents

Attachments replicate in their own phase, streamed in chunks, and the checkpoint only moves past what the target confirmed it stored.

Checked by the replication script, including an attachment added with no document change.

Rolling upgrades

A peer on the previous release keeps replicating with upgraded peers both ways. Its edits show up as conflicts, never as lost writes.

Checked by the mixed-version script against barrel_server 1.11.1.

A mesh, and a browser that goes offline

Cut the link between Paris and Berlin and their edits still meet, relayed through Lyon. Take the browser offline: it keeps reading and writing, counts what it has not pushed, and catches up with one sync.

Three sites and a browser

Cut links, take the browser offline, edit anywhere, then sync. Edits relay through whichever peers are reachable, and every copy ends on the same winner with the same conflicts.

    Demonstration in your browser, following barrel's replication rules

     

    Topologies

    One protocol, in the same VM or over HTTP. Arrange the copies the way your network is.

    • Two sites, both ways

      Both take writes; a task in each direction keeps them close.

    • Hub and edges

      Edges push to a hub and pull back what others wrote.

    • A subset per device

      A channel or a query filter decides what each copy gets.

    • Browsers

      barrel-lite keeps a copy in the browser and syncs over the same wire.

    One run, step by step

    A one-shot run and a continuous task do the same thing; a task just keeps doing it.

    1. 1

      Read the checkpoint to find the last change shipped.

    2. 2

      Fetch changes since then, filtered at the source.

    3. 3

      Ask the target which versions it lacks, in one round trip.

    4. 4

      Send the missing document states; applying one twice is harmless.

    5. 5

      Checkpoint the batch, then send the attachments.

    Set it up

    Between two databases on one node

    Run it again later to pick up new changes; it resumes from its checkpoint.

    {ok, Result} = barrel_rep:replicate(<<"paris">>, <<"lyon">>),
    #{docs_written := N} = Result.

    To another node, over HTTP

    The other side is a database under a running barrel_server.

    Lyon = barrel_rep_transport_http:endpoint(
        <<"http://lyon.example:8080/db/tasks">>),
    
    %% push, then pull
    {ok, _} = barrel_rep:replicate(<<"tasks">>, Lyon,
        #{target_transport => barrel_rep_transport_http}),
    {ok, _} = barrel_rep:replicate(Lyon, <<"tasks">>,
        #{source_transport => barrel_rep_transport_http}).

    Keep it running

    A task survives restarts and catches up after an outage. In the browser, barrel-lite syncs over the same wire.

    {ok, TaskId} = barrel_rep_tasks:start_task(#{
        source    => <<"tasks">>,
        target    => <<"http://lyon.example:8080/db/tasks">>,
        mode      => continuous,
        direction => both}).

    Credentials come from the server configuration, never from the task itself.

    A conflict, from a recorded run

    Both sites edited task:1 while apart, then replicated both ways.

    barrel_docdb:get_conflicts(<<"edge_a">>, <<"task:1">>).
    
    {ok, #{<<"_observed">> := Seen}} =
        barrel_docdb:get_doc(<<"edge_a">>, <<"task:1">>,
                             #{conflicts => true}).
    
    barrel_docdb:resolve_conflict(<<"edge_a">>, <<"task:1">>,
        Seen, {merge, Merged}).
    Output of get_conflicts and resolve_conflict, recorded on barrel_docdb 2.1.0
    {ok,[<<"000001a1b879d59100000000@w7bcb971434496877">>]}
    
    {ok,#{id => <<"task:1">>, conflicts_resolved => 1,
          rev => <<"000001a1b879d59500000000@w7bcb971434496877">>}}

    After one more replication, edge_b holds the resolved version and no conflict.

    What does not replicate yet

    • Vector indexes. With record mode the text and metadata replicate and each copy rebuilds its index; a client can pull stored vectors with the documents.
    • Provenance. Who wrote a document stays on the origin’s history; on other copies the arrival is recorded as replicated, from that origin.
    • The barrel API. Replication runs on the document layer: call barrel_rep and barrel_rep_tasks with the database name.
    • Client certificates over HTTP/3. Use HTTP/1.1 or HTTP/2 with TLS when you need mTLS between nodes.
    • Channels do not delete documents that leave a channel from the replicas that already hold them.

    The libraries behind it

    Up and down to moveEnter to open