Barrel
FR GitHub

Barrel documentation

Every page is written for a task. Pick where Barrel will run and start there; each page links to the reference it uses.

If you are new to Barrel, start with a quickstart below: in about ten minutes you write a document, read it back and query it. When you know what you want to do, use the sections further down, which group the guides by task. Search finds a guide, a function, a REST route or an MCP tool by name.

Start here

Not sure which? Choose a deployment compares them in one table.

New to Barrel? Read in this order

  1. Overview for developers: what Barrel does today, what it does not do, and which part you need.
  2. One quickstart, embedded, server or browser: whichever matches where you run Barrel.
  3. The record: how a document, its files and its vector stay under one id.
  4. Versions, conflicts, convergence: what Barrel keeps when two copies edit the same document.

Look up any term you meet on the way in the glossary.

By what you want to do

Concepts

Read these before you write code, to learn how Barrel models data: the record, versions, spaces, contexts, and a glossary of the terms the docs use.

The recordVersions, conflicts, convergenceSpaces and capabilitiesContexts and working setsGlossary

Store and query

When you write documents and files and read them back, from Erlang or with BQL queries.

Embed barrel in an Erlang appRecord modeQuery with BQLAttachments

Search

When you find documents by meaning, by keyword, by exact text or regex, and choose the model that computes vectors.

Vector, keyword and hybridSubstring and regexRerankingChoose an embedding provider

Replicate

When several copies of a database exchange changes, and you need to see and resolve conflicts between them.

SynchronizationConflictsUpgrade from 2.0Upgrade to docdb 3 and spaces 2

Agents

When AI agents share data: a space and a token per agent, the MCP endpoint, and a record of who changed what.

Spaces, sessions, handoffsMCP endpointAudit and provenanceIndex a codebase

Timeline

When you try changes on a branch, merge them back, or recover the database as it was earlier.

Branch, merge, recover

Contexts

When one BQL statement must query several datasets by name, on this node or on other nodes.

Query several datasets

Browser

When a web app keeps its own copy of the data with barrel-lite and syncs it with a server.

barrel-lite

Security

When you encrypt data on disk, or decide who can reach the server and with which rights.

Encryption at restAuthentication

Operate

When you run barrel_server for real: start it, embed it, watch it, fix it and back it up.

Run the serverRun in DockerReleasesEmbed the server in an appMonitoringTroubleshootingBackups and recovery

Reference

When you need the exact name of a function, query form, route, MCP tool, option or error code.

Barrel APIBQLREST APIMCP toolsConfigurationError codesLibraries

Architecture

When you want to know how the pieces fit, the status of each feature, and how replication is checked.

OverviewFeature statusReplication proofsContexts designVision

Contribute

When you build Barrel from source, run its tests, write an embedding provider, or ship one app on its own.

Build and testEnd-to-end testsWrite a providerDistribute the apps

Reference, generated from the code

These pages are built from the source, so they match the version you run.

For coding agents

Point your assistant at these instead of letting it guess function names.

https://barrel-db.eu/llms.txt
https://barrel-db.eu/llms-full.txt
https://barrel-db.eu/docs/guides/timeline.md
https://barrel-db.eu/docs/reference/mcp-tools.json

Up and down to moveEnter to open