# Démarrage rapide : serveur

[`barrel_server`](/fr/docs/concepts/glossary#barrel-server) sert Barrel
sur HTTP : une API REST/JSON pour les applications et un point d’accès
[MCP](/fr/docs/concepts/glossary#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.

<Goal items={["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 :
> 
> ```shell
> 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](/fr/docs/guides/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.

```shell
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:

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

Démarrez le serveur :

```shell
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 :

```shell
curl localhost:8080/health
```

Sortie d’une exécution sur barrel_server 1.13.0:

```
{"status":"ok"}
```

> **Note:** 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](/fr/docs/security/authentication).

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

```shell
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"}
```

> **Note:** `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.

```shell
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"}
```

> **Note:** L’écriture répond avec `rev`, le jeton de
> [révision](/fr/docs/concepts/glossary#revision) 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é :

```shell
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"}
```

> **Note:** `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` :

```shell
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](/fr/docs/concepts/glossary#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`.

```shell
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}}
```

> **Note:** 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](/fr/docs/guides/query-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 :

```shell
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"}}}
```

> **Note:** 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 :

```shell
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"}]}}
```

> **Note:** 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](/fr/docs/guides/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](/fr/docs/guides/rest-server).
- `/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é.

<NextSteps steps={[
  { href: '/docs/security/authentication', label: 'Authentification', why: 'Verrouillez le serveur avant que d’autres puissent atteindre son port.' },
  { href: '/docs/guides/rest-server', label: 'Lancer le serveur', why: 'Voyez chaque route, les bornes de requête, CORS et les réglages d’authentification.' },
  { href: '/docs/guides/mcp', label: 'Point d’accès MCP', why: 'Branchez un environnement d’agents sur le serveur.' },
  { href: '/docs/start/quickstart-browser', label: 'Démarrage rapide : navigateur', why: 'Gardez une copie d’une base dans une application web et synchronisez-la avec ce serveur.' },
]} />
