Barrel
EN GitHub

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.
Sans compilation : utilisez l’image

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.9

Sans 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 :

sys.config
[{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
Sortie d’une exécution sur barrel_server 1.13.0
{"status":"ok"}
Ce qui vient de se passer

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.

Limite

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
Sortie d’une exécution sur barrel_server 1.13.0
HTTP/1.1 201 Created
{"ok":true,"db":"demo"}
Ce qui vient de se passer

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
Sortie d’une exécution sur barrel_server 1.13.0
{"id":"a","ok":true,
"rev":"000001a1b876972d00000000@w78160d59891ba7d7"}
{"_rev":"000001a1b876972d00000000@w78160d59891ba7d7",
"id":"a","kind":"note","n":1,"title":"hello world"}
Ce qui vient de se passer

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"}'
Sortie d’une exécution sur barrel_server 1.13.0
HTTP/1.1 409 Conflict
{"error":"conflict"}
Ce qui vient de se passer

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"
Sortie d’une exécution sur 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}}
Ce qui vient de se passer

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"}}}'
Sortie d’une exécution de l’image Barrel 2026.11.9 (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"}}}
Ce qui vient de se passer

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 :

Sortie d’une exécution sur 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"}]}}
Ce qui vient de se passer

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/bm25 et /search/hybrid répondent donc 500 tant que vous ne les configurez pas. Voir Faire tourner le serveur.
  • /health renvoie 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é.

Traduit de la page anglaise: /docs/start/quickstart-server/ Modifier cette page Voir en Markdown

Haut et bas pour se déplacerEntrée pour ouvrir