Présentation des drivers

Le projet arcadedb-drivers propose quatre paquets : un driver HTTP et un driver gRPC pour Python, ainsi que leurs équivalents pour TypeScript/JavaScript. Tous sont distribués sous licence Apache‑2.0, générés à partir des contrats OpenAPI et Protobuf publiés par ArcadeDB, et disponibles sur les registres publics depuis la version 0.1.0. Les paquets Python requièrent Python 3.10 ou supérieur, tandis que les paquets TypeScript exigent Node 20+ et sont strictement ESM.

Transports HTTP vs gRPC

ArcadeDB expose deux protocoles : HTTP et gRPC. Le driver HTTP fonctionne partout, ne dépend que de fetch (TypeScript) ou httpx (Python), et suffit pour la majorité des charges où le protocole n’est pas le facteur limitant. Le driver gRPC, quant à lui, offre un débit supérieur mais ne dispose d’aucune implémentation côté navigateur : le serveur utilise grpc-java sur HTTP/2 via Netty, sans support gRPC‑Web, Connect ou servlet, ce qui empêche tout client de navigateur d’établir la connexion.

Gestion des requêtes et des transactions

Les deux drivers HTTP renvoient un enveloppe de réponse contenant result, limit, returned et truncated. Le champ truncated indique que le sérialiseur du serveur a atteint le plafond arcadedb.server.httpQueryMaxResultRows avant d’avoir épuisé le jeu de résultats, ce qui rend indispensable la vérification du drapeau pour éviter des réponses partielles. Exemple de requête Python :

from arcadedb_driver import ArcadeDBServer, basic_auth
with ArcadeDBServer(base_url="http://localhost:2480", auth=basic_auth("root", "playwithdata")) as srv:
    db = srv.db("mydb")
    envelope = db.query(language="sql", command="SELECT FROM Person WHERE age > ?", params={"1": 21})
    print(envelope.result)

En TypeScript :

import { createClient, basicAuth } from "@arcadedb/driver";
const server = createClient({
  baseUrl: "http://localhost:2480",
  auth: basicAuth("root", "playwithdata"),
});
const db = server.db("mydb");
const { result } = await db.query({
  language: "sql",
  command: "SELECT FROM Person WHERE age > ?",
  params: { 1: 21 },
});

Les transactions sont encapsulées dans des gestionnaires natifs : with srv.db(...).transaction() as tx: en Python et une fonction callback en TypeScript. Tous les appels effectués via le handle tx participent à la même session serveur; un appel accidentel via le handle db déclenche un auto‑commit hors transaction. En cas d’exception, le driver effectue un rollback et transmet l’erreur d’origine, en attachant éventuellement la cause du rollback (__cause__ ou err.cause). Si le commit échoue, un rollback de secours est lancé avant de propager l’erreur.

Limites et perspectives

Les versions 0.1.0 ciblent le serveur ArcadeDB 26.9.1 et chaque README propose une table de compatibilité. Le manque de support gRPC‑Web constitue la principale contrainte côté client : les applications web doivent recourir au driver HTTP, même si le débit gRPC serait théoriquement supérieur. De plus, le paramètre serveur arcadedb.server.httpTxExpireTimeout détermine la durée maximale avant qu’une session transactionnelle abandonnée ne soit nettoyée, ce qui impose aux développeurs de gérer explicitement la clôture des blocs transactionnels. Les prochains jalons prévoient l’ajout de nouveaux langages et, potentiellement, une évolution du serveur pour exposer un endpoint gRPC‑Web, ce qui élargirait l’usage du driver gRPC aux environnements front‑end.