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.
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.9Without 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:
[{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
{"status":"ok"} 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.
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
HTTP/1.1 201 Created
{"ok":true,"db":"demo"} 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
{"id":"a","ok":true,
"rev":"000001a1b876972d00000000@w78160d59891ba7d7"}
{"_rev":"000001a1b876972d00000000@w78160d59891ba7d7",
"id":"a","kind":"note","n":1,"title":"hello world"} 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"}'
HTTP/1.1 409 Conflict
{"error":"conflict"} 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"
{"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}} 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"}}}'
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"}}} 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:
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"}]}} 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/bm25and/search/hybridanswer 500 until you configure them. See Run the server. /healthreturns ok without checking anything. Point a load balancer or orchestrator at/readyinstead: it answers 503{"status":"not_ready","failed":[...]}when a database or replication process is down.