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.
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.
Links
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.
- ParisLyon push and pull
Two sites, both ways
Both take writes; a task in each direction keeps them close.
- hubedge 1edge 2edge 3 continuous tasks
Hub and edges
Edges push to a hub and pull back what others wrote.
- centralchannel mobile filter at the source
A subset per device
A channel or a query filter decides what each copy gets.
- barrel_servertab Atab B /db/:db/_sync
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
Read the checkpoint to find the last change shipped.
- 2
Fetch changes since then, filtered at the source.
- 3
Ask the target which versions it lacks, in one round trip.
- 4
Send the missing document states; applying one twice is harmless.
- 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}). import { Database } from "barrel-lite";
const db = await Database.open("tasks", {
remote: { url: "https://lyon.example:8080",
db: "sp_...", token: "bsp_..." },
});
const live = db.liveSync(); // push and pull, adaptive
// live.stop(); 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}). {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_repandbarrel_rep_taskswith 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.