Démarrage rapide : serveur
barrel_server sert Barrel
sur HTTP : une API REST/JSON pour les applications et un point d’accès
MCP pour les agents. Dans ce démarrage
rapide, vous le compilez depuis les sources, le démarrez, créez une base,
écrivez et lisez des documents avec curl, lancez une requête, puis vous
accédez aux mêmes données comme le ferait un agent, par des appels
d’outils MCP. Suivez ce parcours quand vos clients ne sont pas écrits en
Erlang, tournent sur d’autres machines, ou sont des agents : tout ce qui
parle HTTP peut utiliser la base, et vous la faites tourner comme un seul
service.
Ce que vous allez faire
- Compiler et démarrer barrel_server
- Créer une base et écrire des documents en REST
- Voir comment une écriture périmée est refusée
- Lancer une requête BQL sur HTTP
- Appeler la base comme des outils MCP
Avant de commencer
- Erlang/OTP 26 ou plus récent, rebar3, CMake et un compilateur C/C++, pour compiler le serveur et ses parties natives.
- git, pour cloner les sources.
curl, pour envoyer les requêtes.
Avec Docker, vous pouvez sauter les étapes 1 et 2. Lancez l’image, puis reprenez à l’étape 3 :
docker run -p 8080:8080 ghcr.io/barrel-db/barrel-server:2026.11.9Sans BARREL_AUTH_TOKENS, elle affiche barrel: no BARREL_AUTH_TOKENS set, the server accepts every request (exécution de l’image 2026.11.9), comme
la compilation ci-dessous. Voir Exécuter barrel dans
Docker.
1. Compiler
Le serveur se trouve dans le dépôt umbrella de Barrel, derrière le profil
de compilation server : vous clonez le dépôt et compilez avec ce
profil.
git clone https://github.com/barrel-db/barrel.git
cd barrel
rebar3 as server compile
2. Configurer et démarrer
Le serveur lit ses réglages dans un fichier sys.config. Il vous en faut
deux : le port d’écoute et le répertoire où les bases sont stockées.
Écrivez-le à la racine du clone :
[{barrel_server, [{http_port, 8080},
{data_dir, "/var/tmp/barrel/data"}]},
{kernel, [{logger_level, notice}]}]. Démarrez le serveur :
erl -noshell -config sys \
-pa _build/server/lib/*/ebin \
-eval 'application:ensure_all_started(barrel_server).'
Pour un shell interactif à la place, lancez rebar3 as server shell, puis
application:ensure_all_started(barrel_server).
Vérifiez qu’il répond :
curl localhost:8080/health
{"status":"ok"} Le serveur tourne et écoute sur le port 8080. /health indique seulement
que l’écouteur HTTP répond ; il ne vérifie pas les bases. GET /ready
répond {"status":"ready"} dès que les processus des bases et de la
réplication tournent.
Ce serveur n’a aucune authentification : quiconque atteint le port peut lire et écrire. Verrouillez-le avant de l’exposer. Voir Authentification.
3. Créer une base
Une base est l’unité dans laquelle vous écrivez, que vous interrogez et
que vous répliquez. Chaque route qui touche aux données commence par
/db/:db, le nom de la base.
curl -X PUT localhost:8080/db/demo
HTTP/1.1 201 Created
{"ok":true,"db":"demo"} 201 Created signifie que la base demo n’existait pas et qu’elle existe
maintenant.
Les noms utilisent des lettres minuscules, des chiffres, _ et -,
jusqu’à 63 octets, et ne commencent pas par _ ; tout autre nom répond
400 invalid_name. Seul PUT /db/:db crée une base : toute autre route
/db/:db/... répond 404 {"error":"db_not_found"} pour une base qui
n’existe pas.
4. Écrire et lire un document
Un document est un objet JSON stocké sous un id. PUT l’écrit à l’id
donné dans l’URL (ici a), GET le relit.
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"} L’écriture répond avec rev, le jeton de
révision de la version créée. La
lecture renvoie vos champs et ce même jeton sous le nom _rev. C’est
ainsi que le serveur sait sur quelle version s’appuie une écriture
ultérieure.
Pour le mettre à jour, envoyez le _rev actuel dans le corps. Si
quelqu’un d’autre a modifié le document depuis votre lecture, votre _rev
est périmé et le serveur refuse l’écriture plutôt que de perdre sa
modification. Essayez avec un _rev inventé :
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 signifie que le document n’a pas changé. Relisez-le pour
obtenir le _rev actuel, appliquez votre modification, puis renvoyez-le.
Écrivez-en plusieurs à la fois avec _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. Interroger avec BQL
BQL est le langage de requête de
Barrel, proche de SQL, et chaque champ est indexé : vous pouvez filtrer
sur n’importe quel champ. POST /db/:db/query prend la requête comme
corps et répond en JSON délimité par des sauts de ligne : une
ligne par résultat, puis une ligne meta.
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}} Chaque ligne row est un document qui correspond, avec les champs
sélectionnés. La ligne meta dit comment la réponse s’est terminée :
count lignes, bound vaut limit_reached parce que LIMIT 2 l’a
arrêtée, et has_more vaut false : il n’y a pas de page suivante.
instance_id et last_seq désignent la copie de la base et le point de
son historique de changements que reflète la réponse.
Envoyez plutôt du JSON ({"query": ..., "params": ...}) quand vous passez
des paramètres ou max_rows.
Le nom de collection après FROM est ignoré : la base vient de l’URL.
Voir Interroger avec BQL.
6. L’appeler via MCP
MCP (Model Context Protocol) est le protocole qu’utilisent les
environnements d’agents pour appeler des outils. Le même serveur répond en
MCP sur /mcp (Streamable HTTP) : un agent travaille donc sur les mêmes
bases que vos clients REST. Ici, c’est vous qui jouez l’agent avec
curl. Initialisez d’abord une session et gardez l’en-tête
mcp-session-id qu’elle renvoie :
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"}}} Le serveur a accepté la version de protocole 2025-06-18 et ouvert une
session MCP. L’en-tête mcp-session-id identifie cette session ;
envoyez-le avec chaque requête suivante.
Envoyez notifications/initialized, puis appelez un outil. Chaque
requête après initialize porte l’id de session et la version du
protocole :
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"}}}'
Les appels d’outils répondent en server-sent events. Le résultat de
l’outil est du JSON dans le champ text :
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"}]}} Chaque ligne data: répond à la requête de même id. La requête 2 a
créé la base mcpdemo, la requête 3 a écrit note-1 et reçu son rev,
et la requête 4 a lancé une requête BQL qui l’a trouvée. Ce sont les
mêmes opérations que les appels REST plus haut, présentées comme des
outils.
tools/list renvoie 39 outils. Voir Point d’accès MCP
pour y brancher un agent.
Notes
- Les stockages vectoriels vont à côté des documents sous
data_dir, dans<data_dir>/<name>.vectordb. Un stockage créé avant barrel 1.13.0 dans./priv/sous le répertoire depuis lequel vous avez démarré le serveur continue d’y être utilisé. - Les bases par défaut ont un stockage vectoriel de dimension 768, aucun
embedder et BM25 désactivé :
/search/bm25et/search/hybridrépondent donc 500 tant que vous ne les configurez pas. Voir Faire tourner le serveur. /healthrenvoie ok sans rien vérifier. Pointez plutôt un répartiteur de charge ou un orchestrateur sur/ready: il répond 503{"status":"not_ready","failed":[...]}quand un processus des bases ou de la réplication est arrêté.