Barrel
FR GitHub

Quickstart: browser

barrel-lite is a TypeScript client that keeps a copy of a Barrel database in the browser. Reads and writes are local, so the app answers at once and keeps working offline; sync sends local writes to a barrel_server and brings back the changes made by other copies. In this quickstart you build a small notes app that runs on two devices, a laptop and a phone: you give the browser a scoped token, write a note, sync it to the second device, then edit it on both at once and resolve the conflict. Use this path when a web app must keep working without a network.

What you will do

  • Build barrel-lite and add it to a web app
  • Give the browser a token limited to one space
  • Write and read documents locally
  • Sync two copies through barrel_server
  • Resolve a conflict between two edits

Before you start

1. Get barrel-lite

You build the client from the Barrel source because barrel-lite 0.1.0 is not on npm. Build it from the umbrella and install it into your app from that directory:

cd barrel/clients/barrel-lite
npm ci
npm run build
cd /path/to/your-app
npm install /path/to/barrel/clients/barrel-lite

2. Let the browser in

A web page runs on its own origin and anyone can read its code, so the server must allow cross-origin requests (CORS) and the page must carry a token that grants as little as possible. Add CORS and a global admin token to the server's sys.config and restart it:

sys.config
[{barrel_server, [
  {http_port, 8080},
  {cors, #{origins => '*',
           expose => [<<"x-barrel-hlc">>]}},
  {auth, #{tokens => [<<"global-token">>]}}]}].

Never put the global token in a web page: it opens every database. Instead, create a space, a database created through Barrel's agent layer that you can share, and issue a capability token for it. A capability token grants named rights on one space only, and you can revoke it. The space id is the database name the browser uses:

curl -X POST localhost:8080/spaces \
  -H 'authorization: Bearer global-token' \
  -H 'content-type: application/json' -d '{"label":"app"}'
curl -X POST localhost:8080/spaces/sp_7uitvqeved3z7seu/grants \
  -H 'authorization: Bearer global-token' \
  -H 'content-type: application/json' \
  -d '{"rights":["read","write"]}'
Output from a run on barrel_server 1.13.0
{"ok":true,"space":"sp_7uitvqeved3z7seu"}
{"token":
"bsp_alrw6fxiqga5r47x_odwpp27li6m754pfsuhbwd2n2vxek3ox44hj3zxv",
"grant":{"rights":["read","write"],
        "space":"sp_7uitvqeved3z7seu", ...}}
What just happened

The first call created the space sp_7uitvqeved3z7seu. The second issued a bsp_... token with read and write on that space and nothing else. The token is shown once, since the server stores only a hash of it; copy it now. read covers pulls, write covers pushes.

3. Open, write, read

Database.open creates the local copy and remembers which server database it syncs with. You then write and read as if the database were local, because it is.

import { Database } from "barrel-lite";

const remote = {
  url: "http://localhost:8080",
  db: "sp_7uitvqeved3z7seu",
  token: "bsp_alrw6fxiqga5r47x_...",
};
const laptop = await Database.open("notes", { remote });

await laptop.put({ id: "n1", title: "hello" });
await laptop.get("n1");
Output from a run of barrel-lite 0.1.0 in Node 22
{"id":"n1",
"version":"000001a1ba4159ea00000000@wd31d29e133c6788f"}
{"title":"hello","id":"n1"}
What just happened

put answered with the document id and its version, the revision token of this write, the same token the server calls _rev. get read the note back from the local store. Nothing has reached the server yet.

Writes go to the local store at once. In a browser the store is OPFS; where OPFS is missing (Node, for example) it is in memory.

4. Sync

Sync is how copies catch up with each other. A push sends local writes to the server, a pull applies the changes the server has from other copies, and sync() does both.

await laptop.sync();             // push, then pull
const live = laptop.liveSync();  // keep syncing
live.stop();

Open a second copy the same way, on another device or in another browser. Its first sync brings the document in, and local BQL reads it:

const phone = await Database.open("notes", { remote });
await phone.sync();
await phone.get("n1");
await phone.query(
  "SELECT id, title FROM db WHERE title = 'hello'");
Output from a run of barrel-lite 0.1.0 in Node 22 against barrel_server 1.13.0
{"push":{"pushed":1,"skipped":0,"conflicts":0},
"pull":{"scanned":1,"applied":0}}
{"push":{"pushed":0,"skipped":0,"conflicts":0},
"pull":{"scanned":1,"applied":1}}
{"id":"n1","title":"hello"}
[{"id":"n1","title":"hello"}]
What just happened

The first line is the laptop's sync(): its push sent one document (pushed: 1), and its pull saw one change on the server, its own, so there was nothing to apply. The second line is the phone's: it had nothing to push and applied one change, the note. The phone then reads the note locally, by id and with BQL.

5. Resolve a conflict

Offline copies can change the same note at the same time. Barrel does not drop either edit: both versions are kept, every copy picks the same winner, and the other version is kept as a conflict for you to resolve. Edit the note on both copies before they sync, then sync:

await laptop.put({ id: "n1", title: "hello from the laptop" });
await phone.put({ id: "n1", title: "hello from the phone" });
await laptop.sync(); await phone.sync(); await laptop.sync();

await laptop.get("n1");
await phone.get("n1");
await laptop.conflicts("n1");
Output from a run of barrel-lite 0.1.0 in Node 22 against barrel_server 1.13.0
{"id":"n1","title":"hello from the phone"}
{"id":"n1","title":"hello from the phone"}
[{"version":"000001a1ba415a1600000001@wd31d29e133c6788f",
"deleted":false,
"body":{"id":"n1","title":"hello from the laptop"}}]
What just happened

Both copies show the phone's edit: the winner is the version with the highest token, so every copy reaches the same answer without talking to each other. This is convergence. The laptop's edit is not lost: conflicts returns it with its version and body.

resolve replaces the winner and every conflict with one body. Push it, and the other copy gets the resolution on its next pull:

await laptop.resolve("n1", { title: "hello from both" });
await laptop.push();
await phone.pull();
await phone.get("n1");
await phone.conflicts("n1");
Output from a run of barrel-lite 0.1.0 in Node 22 against barrel_server 1.13.0
{"id":"n1","title":"hello from both"}
[]
What just happened

The phone now reads the resolved body, and its conflict list is empty: the resolution replaced both versions on every copy that pulled it.

put on a document in conflict replaces only the winner; the conflicts stay. Pass null to resolve to resolve to a delete.

Notes

Limit

The local store is a cache. Writes not yet flushed are lost on a crash, and the browser may evict the whole store. The server copy is the source of truth, so sync often.

  • Vector, keyword and hybrid search (vector_top_k, bm25_top_k, hybrid_top_k) and SUBSCRIBE run on the server only; use db.queryRemote. Locally they throw BqlServerOnlyError.
  • barrel-lite authenticates with bearer tokens only, global or capability. It does not sign requests.
  • With multiTab: true one tab syncs and the others go through it.
  • The full client is described in barrel-lite.

Written for the site Edit this page View as Markdown

Up and down to moveEnter to open