Barrel
FR GitHub

Embedded, server or browser: the same database.

Barrel runs inside your Erlang release, behind its own REST and MCP server, or as a local copy in a web page. The record and the replication protocol are the same in all three, so you can start with one and add the others.

Most deployments mix them: agents on a server, edge nodes embedded, users in the browser, all syncing.

Choose a deploymentInstall

How they connect

One sync wire joins them. A browser syncs with a server; servers and embedded nodes replicate with each other in either direction.

  1. Browser tab barrel-lite, OPFS

    /db/:db/_sync, bearer

  2. barrel_server REST, MCP, sync wire

    barrel_rep over HTTP

  3. Your release barrel embedded

Decide

Read across a row to compare. Each column links to its quickstart.

Embedded, server and browser compared
QuestionEmbeddedServerBrowser
Choose it whenYour agents and services are Erlang or Elixir processes in one release.Clients in other languages, agents over MCP, or other nodes need to reach the data.A web app must keep reading and writing while offline.
What runsbarrel as a library in your VM. No network protocol.barrel_server: REST and MCP over HTTP/1.1, HTTP/2 with TLS, or HTTP/3.barrel-lite, a TypeScript client holding a local copy.
You needOTP 26 or later, a C compiler and CMake for the NIFs (RocksDB, the vector index, the trigram index).The same, built with the server profile; port 8080 by default.A barrel_server to sync with, with CORS on and a capability token for the browser.
Data lives inRocksDB under the docdb data_dir, vectors under the store’s db_path.The server’s data_dir. Databases open on first use and close when idle.OPFS when the browser has it, otherwise memory. The server copy is the source of truth.
SearchEverything: vector, BM25, hybrid, BQL table functions, substring and regex.Vector, BM25 and hybrid over REST and MCP; substring and regex over MCP only.Local BQL on documents and brute-force vector search over synced vectors. Keyword and hybrid go to the server.
Replicationbarrel_rep and barrel_rep_tasks on the document database, in the VM or over HTTP.Serves the sync wire at /db/:db/_sync, and runs tasks to other nodes.Push, pull and live sync with one server, leader tab only.
Access controlYour code. Per-database encryption is the boundary between tenants.Bearer, capability tokens, signed requests, mTLS. Open until you set auth.Bearer only: a capability token scoped to one space.
Watch out forThe default vector path is relative to the current directory; set db_path. The vector store is linked to the process that opened it.Default databases have BM25 off; set open_opts. Search configuration errors answer 500.Unflushed writes are lost on a crash and the browser may evict the store. Not published to npm yet.

Optional pieces, in any of them

Not in the default build. Add them where you need them.

  • Embeddings, local or cloud

    A provider in barrel_embed: Ollama, a Python virtualenv for local models, or a cloud API key.

  • Reranking

    barrel_rerank: Python 3 with transformers and torch, about 2 GB, model downloaded on first use.

  • FAISS index

    rebar3 as faiss compile with the FAISS C++ library on the system. Linux, macOS and BSD; no Windows build.

  • S3 attachments

    rebar3 as s3 compile. Tested against RustFS and Garage. Not covered by encryption at rest.

Start

Embedded

rebar.config
{deps, [{barrel, "~> 1.14"}]}.
{ok, _} = application:ensure_all_started(barrel),
{ok, Db} = barrel:open(<<"kb">>, #{vectordb => #{
    db_path => "data/kb_vec", dimensions => 768}}),
{ok, _} = barrel:put_doc(Db, #{<<"id">> => <<"kb-142">>,
    <<"title">> => <<"Reset a locked account">>}).

Server

From the umbrella. During development, rebar3 as server shell then application:ensure_all_started(barrel_server) does the same.

Shell
rebar3 as server,prod release -n barrel_server
cd _build/server+prod/rel/barrel_server
bin/barrel_server foreground
curl localhost:8080/health
Answer from /health
{"status":"ok"}

Browser

barrel-lite is not on npm yet: build it from clients/barrel-lite in the repository.

import { Database } from "barrel-lite";

const db = await Database.open("notes", {
  remote: { url: "https://edge.example:8080",
            db: "sp_...", token: "bsp_..." },
  multiTab: true,
});
await db.put({ id: "n1", title: "hello" });
await db.sync();   // push local writes, then pull

Limits

  • barrel-lite 0.1.0 is not published to npm; you build it from the repository.
  • The embedded API does not expose replication: call barrel_rep on the document database.
  • The server has no switch to turn off its HTTP listener; to serve barrel routes from your own livery service, mount barrel_server_api:routes/1.
  • HTTP/3 listeners do not check client certificates; use HTTP/1.1 or HTTP/2 with TLS for mTLS.
  • In the browser, storage is a cache: sync is what makes a write durable.

The libraries behind it

Up and down to moveEnter to open