Barrel
FR GitHub

Quickstart: server

barrel_server serves Barrel over HTTP: a REST/JSON API for applications and an MCP endpoint for agents. In this quickstart you build it from source, start it, create a database, write and read documents with curl, run a query, then reach the same data as an agent would, through MCP tool calls. Use this path when your clients are not written in Erlang, run on other machines, or are agents: anything that speaks HTTP can use the database, and you run it as one service.

What you will do

  • Build and start barrel_server
  • Create a database and write documents over REST
  • See how a stale write is refused
  • Run a BQL query over HTTP
  • Call the database as MCP tools

Before you start

  • Erlang/OTP 26 or later, rebar3, CMake and a C/C++ compiler, to build the server and its native parts.
  • git, to clone the source.
  • curl, to send requests.
No build: use the image

With Docker you can skip steps 1 and 2. Start the image, then continue at step 3:

docker run -p 8080:8080 ghcr.io/barrel-db/barrel-server:2026.11.9

Without BARREL_AUTH_TOKENS it logs barrel: no BARREL_AUTH_TOKENS set, the server accepts every request (run of the 2026.11.9 image), like the build below. See Run barrel in Docker.

1. Build

The server lives in the Barrel umbrella repository, behind the server build profile, so you clone it and compile with that profile.

git clone https://github.com/barrel-db/barrel.git
cd barrel
rebar3 as server compile

2. Configure and start

The server reads its settings from a sys.config file. You need two: the port to listen on and the directory where databases are stored. Write it at the root of the clone:

sys.config
[{barrel_server, [{http_port, 8080},
                {data_dir, "/var/tmp/barrel/data"}]},
{kernel, [{logger_level, notice}]}].

Start the server:

erl -noshell -config sys \
    -pa _build/server/lib/*/ebin \
    -eval 'application:ensure_all_started(barrel_server).'

For an interactive shell instead, run rebar3 as server shell, then application:ensure_all_started(barrel_server).

Check that it answers:

curl localhost:8080/health
Output from a run on barrel_server 1.13.0
{"status":"ok"}
What just happened

The server is up and listening on port 8080. /health only tells you the HTTP listener answers; it does not check the databases. GET /ready answers {"status":"ready"} once the database and replication processes run.

Limit

This server has no authentication: anyone who can reach the port can read and write. Lock it before you expose it. See Authentication.

3. Create a database

A database is the unit you write to, query and replicate. Every route that works on data starts with /db/:db, the database name.

curl -X PUT localhost:8080/db/demo
Output from a run on barrel_server 1.13.0
HTTP/1.1 201 Created
{"ok":true,"db":"demo"}
What just happened

201 Created means the database demo did not exist and now does.

Names use lowercase letters, digits, _ and -, up to 63 bytes, and must not start with _; any other name answers 400 invalid_name. Only PUT /db/:db creates a database: every other /db/:db/... route answers 404 {"error":"db_not_found"} for a database that does not exist.

4. Write and read a document

A document is a JSON object stored under an id. PUT writes it at the id in the URL (a here), GET reads it back.

curl -X PUT localhost:8080/db/demo/doc/a \
  -H 'content-type: application/json' \
  -d '{"title":"hello world","kind":"note","n":1}'
curl localhost:8080/db/demo/doc/a
Output from a run on barrel_server 1.13.0
{"id":"a","ok":true,
"rev":"000001a1b876972d00000000@w78160d59891ba7d7"}
{"_rev":"000001a1b876972d00000000@w78160d59891ba7d7",
"id":"a","kind":"note","n":1,"title":"hello world"}
What just happened

The write answers with rev, the revision token of the version it created. The read returns your fields plus that same token as _rev. It is how the server knows which version a later write was based on.

To update it, send the current _rev in the body. If someone else updated the document since you read it, your _rev is stale and the server refuses the write instead of losing their change. Try it with a made-up _rev:

curl -X PUT localhost:8080/db/demo/doc/a \
  -H 'content-type: application/json' \
  -d '{"title":"stale","_rev":"bogus"}'
Output from a run on barrel_server 1.13.0
HTTP/1.1 409 Conflict
{"error":"conflict"}
What just happened

409 Conflict means the document was not changed. Read it again to get the current _rev, apply your edit, and send it back.

Write several at once with _bulk_docs:

curl -X POST localhost:8080/db/demo/_bulk_docs \
  -H 'content-type: application/json' \
  -d '{"docs":[{"id":"c","kind":"note","title":"third"},
              {"id":"d","kind":"note","title":"fourth"}]}'

5. Query with BQL

BQL is Barrel's query language, close to SQL, and every field is indexed, so you can filter on any field. POST /db/:db/query takes the query as the body and answers newline-delimited JSON: one line per row, then a meta line.

curl -X POST localhost:8080/db/demo/query \
  -H 'content-type: text/plain' \
  --data-binary "SELECT id, title FROM c
    WHERE kind = 'note' ORDER BY id LIMIT 2"
Output from a run on barrel_server 1.13.0
{"row":{"id":"a","title":"hello world"}}
{"row":{"id":"c","title":"third"}}
{"meta":{"count":2,"bound":"limit_reached",
"last_seq":"AAABobpEb-MAAAAB",
"instance_id":"4552d48d297c5b2b","has_more":false}}
What just happened

Each row line is one matching document, with the fields you selected. The meta line says how the answer ended: count rows, bound is limit_reached because LIMIT 2 stopped it, and has_more is false so there is no next page. instance_id and last_seq name the database copy and the point in its change history the answer reflects.

Send JSON instead ({"query": ..., "params": ...}) when you pass parameters or max_rows.

The collection name after FROM is ignored: the database comes from the URL. See Query with BQL.

6. Call it over MCP

MCP (Model Context Protocol) is the protocol agent runtimes use to call tools. The same server answers MCP at /mcp (Streamable HTTP), so an agent works on the same databases as your REST clients. Here you play the agent with curl. First initialize a session and keep the mcp-session-id header it returns:

curl -i -X POST localhost:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",
       "params":{"protocolVersion":"2025-06-18",
                 "capabilities":{},
                 "clientInfo":{"name":"curl","version":"0"}}}'
Output from a run of the Barrel 2026.11.9 image (barrel_server 1.15.1)
HTTP/1.1 200 OK
content-type: application/json
mcp-session-id: mcp_23d2e1810ba8c2aaa733edf74b6814cf
{"id":1,"jsonrpc":"2.0","result":{"capabilities":{...},
"protocolVersion":"2025-06-18",
"serverInfo":{"name":"barrel","version":"4.5.1"}}}
What just happened

The server agreed on protocol version 2025-06-18 and opened an MCP session. The mcp-session-id header identifies that session; send it with every following request.

Send notifications/initialized, then call a tool. Every request after initialize carries the session id and the protocol version:

SID=mcp_23d2e1810ba8c2aaa733edf74b6814cf
mcp() {
  curl -s -X POST localhost:8080/mcp \
    -H 'content-type: application/json' \
    -H 'accept: application/json, text/event-stream' \
    -H "mcp-session-id: $SID" \
    -H 'mcp-protocol-version: 2025-06-18' -d "$1"
}
mcp '{"jsonrpc":"2.0","method":"notifications/initialized"}'
mcp '{"jsonrpc":"2.0","id":2,"method":"tools/call",
      "params":{"name":"db_create",
                "arguments":{"db":"mcpdemo"}}}'
mcp '{"jsonrpc":"2.0","id":3,"method":"tools/call",
      "params":{"name":"doc_put","arguments":{"db":"mcpdemo",
        "doc":{"id":"note-1","title":"stored over MCP"}}}}'
mcp '{"jsonrpc":"2.0","id":4,"method":"tools/call",
      "params":{"name":"query","arguments":{"db":"mcpdemo",
        "query":"SELECT id, title FROM c LIMIT 5"}}}'

Tool calls answer as server-sent events. The tool result is JSON in the text field:

Output from a run on barrel_server 1.13.0
data: {"id":2,"jsonrpc":"2.0","result":{"content":[{"text":
"{\"ok\":true,\"db\":\"mcpdemo\"}","type":"text"}]}}

data: {"id":3,"jsonrpc":"2.0","result":{"content":[{"text":
"{\"id\":\"note-1\",\"ok\":true,\"rev\":
\"000001a1ba44713d00000000@w1b9de1b98c6d4949\"}",
"type":"text"}]}}

data: {"id":4,"jsonrpc":"2.0","result":{"content":[{"text":
"{\"count\":1,\"rows\":[{\"id\":\"note-1\",
\"title\":\"stored over MCP\"}],\"has_more\":false}",
"type":"text"}]}}
What just happened

Each data: line answers the request with the same id. Request 2 created the database mcpdemo, request 3 wrote note-1 and got its rev, and request 4 ran a BQL query that found it. These are the same operations as the REST calls above, named as tools.

tools/list returns 39 tools. See MCP endpoint to point an agent at it.

Notes

  • Vector stores go next to the documents under data_dir, as <data_dir>/<name>.vectordb. A store created before barrel 1.13.0 in ./priv/ under the directory you started the server from keeps being used there.
  • Default databases have a 768-dimension vector store, no embedder and BM25 off, so /search/bm25 and /search/hybrid answer 500 until you configure them. See Run the server.
  • /health returns ok without checking anything. Point a load balancer or orchestrator at /ready instead: it answers 503 {"status":"not_ready","failed":[...]} when a database or replication process is down.

Written for the site Edit this page View as Markdown

Up and down to moveEnter to open