Barrel
FR GitHub

Overview for developers

Barrel is an open source database, written in Erlang/OTP, for agents and applications that run close to their data. One record holds a JSON document, its attachments and its vector under the same id. You search it by field, by keyword, by meaning or by regex, and you replicate it between copies that all accept writes. Read this page first to know what Barrel does today, what it does not do, and which part you need.

The core ideas

A few ideas come back on every page of these docs. Each one is explained here in plain words, with a link to its glossary entry.

A record keeps everything about one thing under one id. A record is a JSON document, the files attached to it (attachments) and its vector. For a support article such as kb-142, that is its fields, an attached screenshot, and the numbers that describe what its text means. You never keep two stores in step by hand.

Every write gets a revision. When you write a document, Barrel adds a revision token, _rev. To update the document you send that token back, so Barrel knows which version you edited. A write based on a stale version is refused instead of silently replacing a newer one.

Search by meaning comes from embeddings. An embedding is a vector computed from text by a model, so that texts with a similar meaning get close vectors. That is how "I cannot log in" finds "Reset a locked account". In record mode you name the fields to embed, and Barrel computes the vectors and keeps them in step with every write and delete. Hybrid search adds BM25 keyword ranking for exact terms.

Every copy takes writes. Replication copies changes between databases, in one direction or both, and every copy accepts writes (active-active). When two copies change the same document at the same time, both versions are kept: one is the winner and the other is a conflict you can resolve. Every copy picks the same winner, so they end up identical; this is convergence.

Agents share data through spaces. A space is a database created through Barrel's agent layer so that several agents can work on it. Access is given with a capability token, which grants named rights (read, write) on one space and can be revoked. A handoff passes a task and its space from one agent to another.

A database has a timeline. You can create a branch, a separate copy of the database to try changes on, and merge it back later. A branch taken at a past instant gives you point-in-time recovery.

What you get

  • One record per id. A document, its attachments and its embedding live together. In record mode Barrel embeds the fields you name and keeps the vector index in step with every write and delete.
  • Queries. Every path is indexed. You query with BQL, a small SQL-like language, or with find/2 from Erlang.
  • Search. Vector, BM25 keyword and hybrid search, plus exact substring and regex search. See Vector, keyword and hybrid.
  • Replication. Every copy takes writes. Concurrent edits are kept as siblings and every copy shows the same winner. See Versions, conflicts, convergence.
  • Timeline. Branch a database, merge the branch back, or branch at a past instant. See Branch, merge, recover.
  • Agent layer. Spaces shared by capability tokens, sessions with a TTL, handoffs, and an MCP endpoint. See Spaces and capabilities.
  • Security. Encryption at rest per database, bearer and capability tokens, signed requests and mTLS. See Authentication.

How you run it

You use the same database in three ways, depending on where your code runs. They replicate with each other, so you can start with one and add another later.

ModeWhat it isStart here
EmbeddedThe barrel library inside your OTP releaseQuickstart: embedded
Serverbarrel_server: REST/JSON and MCP over HTTPQuickstart: server
Browserbarrel-lite: a local copy in a web app, synced to a serverQuickstart: browser

Choose a deployment compares them.

The parts

Barrel is one database made of separate Apache 2.0 libraries. You can depend on barrel for everything, or on a single library when you need only that part, for example barrel_docdb for documents and sync without vectors.

LibraryRole
barrelThe API in these docs: documents, files and vectors under one id
barrel_docdbDocuments, versions, BQL, attachments, replication
barrel_vectordbVector index (HNSW, DiskANN, FAISS), BM25, hybrid
barrel_ngramExact substring and regex index
barrel_embedEmbedding providers, local or cloud
barrel_rerankCross-encoder reranking (optional)
barrel_spacesSpaces, capability tokens, sessions, handoffs
barrel_serverREST/JSON and MCP server
barrel-liteTypeScript browser client

See Libraries for the per-library references.

What it does not do

These limits are true today. Check them before you design around Barrel.

  • Vectors are not replicated. Documents and attachments replicate. In record mode each copy rebuilds its vector index from the documents.
  • BQL has no aggregates, joins or GROUP BY. COUNT(*) is a syntax error.
  • No backup command. You copy data with a branch, an export, or replication. See Backups and recovery.
  • No metrics route on the server. Metrics are exported from Erlang. See Monitoring.

The feature status page lists what is planned.

Written for the site Edit this page View as Markdown

Up and down to moveEnter to open