ArcadeDB lanza drivers nativos para Python y TypeScript

ArcadeDB por fin tiene clientes nativos en Python y TypeScript

Hasta hoy, integrar ArcadeDB desde Python o Node significaba elegir entre dos males: escribir llamadas HTTP a mano contra la REST API, o "tomar prestado" un driver construido para otra base de datos y conformarse con el subconjunto de operaciones que ese protocolo expone por casualidad. Los dos enfoques funcionan. Ninguno se siente nativo.

Eso cambia con arcadedb-drivers, un nuevo repositorio de ArcadeData que publica cuatro clientes en su versión 0.1.0: drivers HTTP y gRPC para Python, y drivers HTTP y gRPC para TypeScript/JavaScript. Los cuatro son Apache-2.0, los cuatro se generan a partir de contratos que el propio ArcadeDB publica, y los cuatro ya están disponibles en los registros públicos (pip y npm).

Para founders que evalúan stacks de datos, la novedad importa porque resuelve un punto de fricción concreto: hasta ahora, la promesa multi-modelo de ArcadeDB — grafo, documento, clave/valor, series de tiempo, vector y geoespacial en un solo motor — chocaba contra la realidad de que hablarle desde Python o JS era, en el mejor de los casos, un compromiso.

Qué es ArcadeDB y por qué importa este lanzamiento

ArcadeDB es una base de datos multi-modelo escrita en Java por Luca Garulli, el mismo creador de OrientDB (adquirida por SAP), según describe el repositorio oficial del proyecto en GitHub. Soporta SQL, Cypher (compatible con Neo4j), Gremlin (Apache TinkerPop), GraphQL y el lenguaje de consultas de MongoDB, y puede correr embebida o remota vía HTTP, gRPC, o drivers de Postgres, Redis o MongoDB.

El lanzamiento de drivers nativos generados desde contrato no es una mejora menor: es un cambio de plataforma. Significa que cualquier startup puede tratar ArcadeDB como una dependencia más en su requirements.txt o package.json, sin tener que mantener un cliente HTTP custom o rezar para que el driver de otra DB siga siendo compatible.

Los cuatro paquetes y cuándo usar cada uno

Paquete	Lenguaje	API	Instalación
arcadedb-driver	Python	HTTP	pip install arcadedb-driver
arcadedb-driver-grpc	Python	gRPC	pip install arcadedb-driver-grpc
@arcadedb/driver	TypeScript/JS	HTTP	npm install @arcadedb/driver
@arcadedb/driver-grpc	TypeScript/JS	gRPC	npm install @arcadedb/driver-grpc

Los cuatro asumen despliegue cliente-servidor (no embebido). Los paquetes de Python requieren Python 3.10+; los de TypeScript requieren Node 20+ y son solo ESM (importar con import, no con require()). La versión 0.1.0 apunta al servidor ArcadeDB 26.9.1, y cada README trae una tabla de compatibilidad driver-servidor.

HTTP o gRPC: cómo elegir sin perder una tarde

La regla de oro del propio equipo de ArcadeDB es empezar con HTTP. "Funciona en todas partes, no necesita nada más allá de fetch o httpx, y para la mayoría del tráfico de aplicaciones el protocolo no es el cuello de botella", señala el anuncio. Migrar una carga de trabajo a gRPC solo cuando se pueda apuntar a un número de throughput que lo justifique.

Cuándo HTTP es la opción correcta:

• Estás escribiendo código de navegador.
• Quieres la menor cantidad de dependencias.
• Estás en una función serverless con cold starts que preocupan.
• Tu tráfico es request/response ordinario.
• Quieres reutilizar infraestructura HTTP existente: proxies, gateways, tracing.

Cuándo conviene saltar a gRPC:

• Estás escribiendo código server-to-server.
• Estás leyendo un result set grande y quieres streamearlo.
• Estás haciendo bulk-insert con una conexión de larga duración.
• Tu tráfico es sensible al throughput y sostenido.
• Necesitas streaming bidireccional nativo.

Una limitación clave: no existe build de navegador para el driver gRPC, y no la habrá hasta que el servidor cambie. El GrpcServerPlugin de ArcadeDB es grpc-java plano sobre HTTP/2, construido sobre Netty, sin handler gRPC-Web, sin protocolo Connect, sin adaptador servlet. Un navegador no puede hablar framing gRPC sobre HTTP/2 crudo, así que ningún cliente puede llegar a este servidor desde una pestaña. Para código de navegador: HTTP.

Conectarse y consultar: el código que vas a escribir mañana

Los drivers HTTP son el punto de entrada natural. En Python, de forma síncrona:

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)

La fachada asíncrona replica la síncrona método por método. En TypeScript, la misma consulta:

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 },
});

Un bearer token funciona igual en ambos lenguajes: cambia basic_auth por bearer_auth (o basicAuth por bearerAuth).

Un detalle que ahorra horas en producción: omitir el timeout en httpx desactiva los timeouts por completo en lugar de caer al default de cinco segundos, porque en httpx un timeout=None explícito significa exactamente eso. Si quieres requests acotados, pasa un httpx.Timeout.

Como ArcadeDB es multi-modelo, el lenguaje hace trabajo real: "sql", "cypher", "gremlin" — la misma llamada query llega a todos, y al driver no le importa cuál elegiste.

El sobre de respuesta y por qué truncated no es opcional

Ningún driver HTTP devuelve un array de filas pelado. Ambos devuelven el sobre completo:

interface QueryEnvelope<T> {
  result: T[];
  limit: number;
  returned: number;
  truncated: boolean;
}

truncated es true cuando el serializador del servidor llegó al tope de filas mientras la consulta todavía tenía filas por escribir. Cuando eso pasa, result es una respuesta parcial, no una completa y corta, y las dos son indistinguibles por forma: un array de 5.000 filas que se cortó temprano se ve exactamente igual que un array de 5.000 filas que se quedó sin matches. Un driver que desenvuelve el sobre y devuelve solo result te estaría entregando un valor que no podés verificar.

La regla: cuando truncated sea true, re-consulta con un filtro más estrecho o un limit más alto. Subir limit no siempre es la solución: si el resultado real supera el techo duro del servidor (arcadedb.server.httpQueryMaxResultRows), la consulta se rechaza con un 413 en lugar de truncarse. A partir de ahí, el único camino es un filtro más estrecho.

Transacciones: el error que cuesta un día

Ambos drivers HTTP envuelven las sesiones de transacción del lado del servidor en el idioma que su lenguaje ya tiene. Python usa context manager; TypeScript usa callback. La regla en ambos es la misma, y es la que hay que acertar: toda llamada que deba participar en la transacción va por el handle tx, no por el objeto db exterior. Una llamada hecha por el handle exterior mientras hay una transacción abierta hace auto-commit por su cuenta, fuera de la transacción, exactamente como si no hubiera transacción abierta.

El contrato de commit/rollback tiene tres cláusulas: el bloque sale limpio y la transacción commitea; el bloque lanza excepción y la transacción hace rollback, con la excepción original propagándose (si el rollback también falla, ese fallo se adjunta como __cause__ en Python o err.cause en TypeScript en lugar de reemplazar el error que querías ver); y si el commit falla, se emite un rollback best-effort primero, para no dejar la sesión del lado del servidor abierta hasta que arcadedb.server.httpTxExpireTimeout la reaper, antes de re-lanzar el error del commit.

Streaming sobre gRPC: cuando el request/response no alcanza

Los drivers gRPC existen para las cargas donde la forma request/response de HTTP es el costo. Un result set grande sobre HTTP significa paginar con llamadas repetidas; sobre gRPC es un único stream.

Una regla de seguridad que los drivers gRPC aplican en código en lugar de documentar y esperar: password_auth envía la contraseña en metadatos gRPC en texto plano, así que create_client se rehúsa a emparejarla con un canal sin credenciales de transporte a menos que pases insecure=True y digas que lo querés así. Un bearer token no es una contraseña y nunca dispara esta guardia.

El driver expone tres wrappers sobre el stub generado para los RPCs que el stub solo maneja mal: stream_query, insert_stream y transaction. streamQuery aplana el stream de batches de filas del servidor en una fila a la vez, y eso es lo único que hace. Deliberadamente no elige retrievalMode por vos, porque los tres modos (CURSOR, MATERIALIZE_ALL, PAGED) difieren en formas que solo el caller puede sopesar.

Un contrato, muchos clientes: la apuesta de fondo

En un año, los cuatro paquetes importarán menos que de dónde viene su código. El directorio contracts/ del repositorio contiene dos archivos: la especificación OpenAPI de la que se genera cada cliente HTTP, y el .proto de Protobuf del que se genera cada cliente gRPC. Ambos se fetchean desde ArcadeDB mismo; ninguno se mantiene a mano en paralelo. Ningún paquete cliente edita sus tipos generados. El build de cada cliente regenera desde el contrato y falla en una puerta de drift: si el código generado commiteado y una regeneración fresca no coinciden, el build se rompe en lugar de publicar un cliente que describe silenciosamente un servidor que ya no existe.

Este es el modo de fallo al que apunta el diseño, según el anuncio oficial. Los drivers escritos a mano se pudren en silencio. El servidor agrega un campo o ajusta una respuesta, y el driver sigue compilando y devolviendo valores plausibles hasta que alguien pierde un día por eso. Un cliente generado con drift gate no llega ahí: el desacuerdo se convierte en un build rojo el día que el contrato se mueve, y agregar un lenguaje después significa escribir una config de generador, no releer el código del servidor y escribir tipos a mano.

Dos detalles chicos siguen de la misma idea. Cada release se construye y publica por CI desde un checkout limpio, nunca desde la laptop de nadie: los paquetes npm llevan attestation de provenance, y los paquetes PyPI salen por trusted publishing sin tokens de larga vida en la cadena. Y nada se publica automáticamente. Cada release es un workflow dispatch disparado por humanos.

¿Qué significa esto para tu startup?

Si tu stack ya tiene ArcadeDB como dependencia de datos — o si lo estabas evaluando y el soporte de cliente era una barrera — los drivers nativos eliminan la categoría entera de "cliente HTTP custom mantenido a mano" del backlog. Lo que antes era trabajo de plomería se vuelve pip install o npm install.

Tres acciones concretas que podés tomar esta semana:

• Auditar tu capa de acceso a ArcadeDB. Si hoy dependés de un cliente HTTP ad-hoc o del driver de otra DB, mapeá qué porcentaje de la API nativa estás usando. Con un driver nativo generado desde contrato, ese porcentaje puede acercarse al 100% sin escribir código a mano.
• Evaluar gRPC para cargas bulk. Si hacés inserts masivos o leés result sets grandes (por ejemplo, en pipelines de grafos para RAG o detección de fraude, casos que el propio repositorio de ArcadeDB documenta), el stream gRPC cambia la complejidad operacional: una conexión de larga vida en lugar de paginación.
• Pin la versión y leé el changelog antes de升级. Son releases 0.1.0 en heavy development. Las APIs listadas son las que el equipo pretende mantener, pero algunas cambiarán antes de 1.0. Fijá una versión si necesitás que la superficie quede quieta.

El roadmap: más lenguajes en camino

El repositorio ya está diagramado para recibir más lenguajes: go/ y otros directorios de lenguaje aparecerán como hermanos de typescript/ y python/, cada uno generado desde los mismos dos contratos. Ninguno existe todavía, pero el diseño contract-first es lo que hace que agregar uno sea manejable: una config de generador, no re-leer el código del servidor.

Los issues y pull requests van a ArcadeData/arcadedb-drivers. El equipo pide explícitamente: probarlos contra una carga de trabajo real y avisar dónde se interponen.

Fuentes

• Native Python and TypeScript Drivers for ArcadeDB, from OpenAPI and Protobuf (fuente original)
• ArcadeData/arcadedb — GitHub