Native Python and TypeScript Drivers for ArcadeDB, from OpenAPI and Protobuf

Sep 10, 2026 11:14 PM - 4 days ago 2

Until now, talking to ArcadeDB from Python aliases Node meant 1 of 2 things: penning HTTP calls by manus against the REST API, aliases borrowing a driver built for different database and surviving wrong the subset of ArcadeDB that different database’s protocol happens to expose. Both work. Neither is simply a customer anyone would telephone native.

That changes pinch arcadedb-drivers, a caller repository holding 4 published clients: an HTTP driver and a gRPC driver for Python, and an HTTP driver and a gRPC driver for TypeScript/JavaScript. All 4 are Apache-2.0, each 4 are generated from contracts ArcadeDB itself publishes, and each 4 are connected the nationalist registries today. They are besides young: 0.1.0 releases nether dense development, pinch much languages connected the way.

The 4 packages

All 4 talk to a moving server, truthful they presume the client-server deployment alternatively than the embedded one. The Python packages request Python 3.10 aliases newer. The TypeScript packages request Node 20 aliases newer and are ESM only: import them, do not require() them. Version 0.1.0 of each targets ArcadeDB server 26.9.1, and each package README carries a compatibility array mapping driver versions to server versions.

HTTP aliases gRPC?

Two drivers per connection is not indecision. HTTP and gRPC are the 2 transports ArcadeDB speaks, and each handles immoderate workloads amended than the other.

Use the HTTP driver when Use the gRPC driver when

You are penning browser code	You are penning server-to-server code
You want the fewest dependencies	You are reference a ample consequence group and want to watercourse it
You are successful a serverless usability pinch acold starts to interest about	You are bulk-inserting and want 1 long-lived connection
Your postulation is mean request/response	Your postulation is throughput-sensitive and sustained
You want to reuse existing HTTP infrastructure: proxies, gateways, tracing	You want autochthonal bidirectional streaming

Start pinch HTTP. It useful everywhere, it needs thing beyond fetch aliases httpx, and for astir exertion postulation the protocol is not the bottleneck. Move a workload to gRPC erstwhile you tin constituent astatine the throughput number that justifies it.

One constraint is easy to suffer an day to, truthful present it is plainly. There is nary browser build of the gRPC driver, and location will not beryllium 1 until the server changes. ArcadeDB’s GrpcServerPlugin is plain grpc-java complete HTTP/2, built connected Netty, pinch nary gRPC-Web handler, nary Connect protocol, and nary servlet adapter successful beforehand of it. A browser cannot speak earthy HTTP/2 gRPC framing, truthful nary customer room successful immoderate connection tin scope this server from a browser tab. Browser codification uses the HTTP driver. The limit is successful the server.

Connecting and querying

The HTTP drivers are the spot to start. Python, synchronously:

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 property > ?", params={"1": 21}) print(envelope.result)

The async destruction mirrors the sync 1 method for method:

import asyncio from arcadedb_driver import AsyncArcadeDBServer, basic_auth async def main() -> None: async with AsyncArcadeDBServer(base_url="http://localhost:2480", auth=basic_auth("root", "playwithdata")) as srv: db = srv.db("mydb") envelope = await db.query(language="sql", command="SELECT FROM Person WHERE property > ?", params={"1": 21}) print(envelope.result) asyncio.run(main())

Both are discourse managers because some ain an httpx customer pinch its ain relationship excavation that has to beryllium released. One item that surprises group successful production: omitting timeout disables timeouts wholly alternatively of falling backmost to httpx’s five-second default, because successful httpx an definitive timeout=None intends precisely that. Pass an httpx.Timeout if you want requests bounded.

TypeScript, aforesaid query:

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 property > ?", params: { 1: 21 }, });

A bearer token, specified arsenic a convention token returned by /api/v1/login, useful the aforesaid measurement successful some languages: switch basic_auth for bearer_auth, aliases basicAuth for bearerAuth.

Because ArcadeDB is multi-model, connection does existent activity here. "sql", "cypher", "gremlin": the aforesaid query telephone reaches each of them, and the driver does not attraction which 1 you picked.

The consequence envelope, and why truncated matters

Neither HTTP driver returns a bare array of rows. Both return the full consequence envelope:

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

Of each API determination successful the drivers, this is the 1 astir apt to look for illustration pointless ceremony, truthful present is the lawsuit for it. truncated is existent erstwhile the server’s serializer deed its statement headdress while the query still had rows near to write. When that happens, consequence is simply a partial answer, not a short but complete one, and the 2 are indistinguishable by shape: a 5,000-row array that stopped early looks precisely for illustration a 5,000-row array that ran retired of matching records. A driver that unwrapped the letter cover and returned only consequence would beryllium handing you a worth you cannot check.

So cheque it. When truncated is true, re-query pinch a narrower select aliases a higher limit. Raising limit is not ever the fix, though: a consequence whose existent size exceeds the server’s difficult ceiling (arcadedb.server.httpQueryMaxResultRows) is refused outright pinch a 413 alternatively than truncated, and past that constituent a narrower select is the only measurement forward.

Transactions

Both HTTP drivers wrap ArcadeDB’s server-side transaction sessions successful the idiom their connection already has. Python uses a discourse manager:

with srv.db("mydb").transaction() as tx: tx.command(language="sql", command="INSERT INTO Account SET equilibrium = 100") total = tx.query(language="sql", command="SELECT sum(balance) arsenic full FROM Account").result[0]["total"]

TypeScript uses a callback:

The norm successful some is the same, and it is the 1 to get right: every telephone that should return portion successful the transaction goes done the tx handle, not the outer db entity you opened it from. A telephone made done the outer grip while a transaction is unfastened auto-commits connected its own, extracurricular the transaction, precisely arsenic if nary transaction were open.

The perpetrate and rollback statement has 3 clauses successful some languages. The artifact exits cleanly and the transaction commits. The artifact raises and the transaction rolls back, pinch the block’s ain objection propagating: if the rollback besides fails, that nonaccomplishment is attached arsenic __cause__ (Python) aliases err.cause (TypeScript) alternatively than replacing the correction you really asked about. And if the perpetrate itself fails, a best-effort rollback is issued first, truthful the server-side convention is not near unfastened until arcadedb.server.httpTxExpireTimeout reaps it, earlier the commit’s correction is re-raised.

Streaming, complete gRPC

The gRPC drivers beryllium for the workloads wherever HTTP’s request/response style is the cost. A ample consequence group complete HTTP intends paging done repeated calls; complete gRPC it is 1 stream.

from arcadedb_driver_grpc import create_client, messages with create_client("localhost:50051", insecure=True) as client: response = client.raw.ExecuteQuery( messages.ExecuteQueryRequest(database="mydb", query="SELECT FROM Person WHERE property > 21", language="sql") )

Note the target: gRPC’s autochthonal host:port form, not a URL. There is nary strategy to parse and thing to default, truthful you walk credentials=grpc.ssl_channel_credentials() for TLS aliases opportunity insecure=True explicitly.

raw is the generated stub for the full ArcadeDbService, truthful each RPC successful the statement is reachable done it. On top, each customer adds 3 wrappers for the RPCs the generated stub unsocial handles badly: stream_query, insert_stream, and transaction. Streaming a query successful TypeScript:

for await (const row of grpc.streamQuery({ database: "mydb", query: "SELECT FROM Person", language: "sql", })) { console.log(row.rid, row.properties); }

streamQuery flattens the server’s watercourse of statement batches into 1 statement astatine a time, and that is the only point it does. It deliberately does not prime retrievalMode for you, because the 3 modes disagree successful ways only the caller tin weigh:

CURSOR, the default: runs the query erstwhile and streams results arsenic you iterate. Pick it for a ample consequence group you want to bound representation on.
MATERIALIZE_ALL: loads the full consequence group connected the server first, past emits it successful batches. Pick it erstwhile you request a unchangeable snapshot and tin spend to clasp it server-side.
PAGED: re-issues the query pinch LIMIT/SKIP per batch. Pick it erstwhile you want each batch’s consistency independent of the others.

Streaming inserts activity the different measurement round. You manus insert_stream an async iterable of statement batches, determine yourself really galore rows spell successful a batch, and the driver owns the letter cover bookkeeping that is easy to get incorrect by hand: 1 unchangeable convention id for the full stream, chunk_seq starting astatine 1 and incrementing, database group connected the first chunk only, and last: existent connected the last one.

One information norm the gRPC drivers enforce successful codification alternatively of documenting and hoping. password_auth sends the password successful plaintext gRPC metadata, truthful create_client refuses to brace it pinch a transmission that has nary carrier credentials unless you walk insecure=True and opportunity you meant it:

create_client("localhost:50051", auth=password_auth("root", "playwithdata")) # raises InsecureChannelError create_client("localhost:50051", auth=password_auth("root", "playwithdata"), credentials=grpc.ssl_channel_credentials()) # fine, the transmission is encrypted

A bearer token is not a password and ne'er trips this guard.

One contract, galore clients

In a year, the 4 packages will matter little than wherever their codification comes from.

contracts/ successful the repository holds 2 files: the OpenAPI specification each HTTP customer is generated from, and the Protobuf .proto each gRPC customer is generated from. Both are fetched from ArcadeDB itself; neither is maintained by manus alongside it. No customer package edits its generated types. Each client’s build regenerates from the statement and fails connected a drift gate: if the checked-in generated codification and a caller regeneration disagree, the build breaks alternatively than shipping a customer that softly describes a server that nary longer exists.

This is the nonaccomplishment mode the creation is aimed at. Hand-written drivers rot silently. The server adds a section aliases tightens a response, and the driver keeps compiling and keeps returning plausible values until personification loses a time to it. A generated customer pinch a drift gross cannot get there: the disagreement becomes a reddish build the time the statement moves, and adding a connection later intends penning a generator config, not re-reading the server’s root and hand-writing types.

Two smaller things travel from the aforesaid idea. Every merchandise is built and published by CI from a cleanable checkout, ne'er from anyone’s laptop: the npm packages transportation provenance attestations, and the PyPI packages spell retired done trusted publishing pinch nary long-lived token anyplace successful the chain. And thing publishes automatically. Every merchandise is simply a human-triggered workflow dispatch.

What is next

These drivers are nether dense development. They are 0.1.0 releases, and while the APIs supra are the ones we intend to keep, immoderate of them will alteration earlier 1.0. Pin a type if you request the aboveground to clasp still, and publication the changelog earlier you move disconnected it.

More languages are planned. The repository is already laid retired for them: go/ and different connection directories will look arsenic siblings of typescript/ and python/, each generated from the aforesaid 2 contracts. None beryllium yet, but the contract-first creation is what makes adding 1 tractable.

Run them against a existent workload and show america wherever they get successful the way. Issues and propulsion requests spell to ArcadeData/arcadedb-drivers.

Repository: github.com/ArcadeData/arcadedb-drivers
Documentation: Native drivers
Packages: arcadedb-driver and arcadedb-driver-grpc connected PyPI, @arcadedb/driver and @arcadedb/driver-grpc connected npm