Native Drivers

Which page do I want?

  • Building a new application in Python, JavaScript/TypeScript or Go — start here.

  • Prefer the clients you already have in Python — Python quickstart, which teaches psycopg, the Neo4j driver and httpx against ArcadeDB.

  • Prefer the clients you already have in JavaScript/TypeScript — JavaScript / TypeScript quickstart, which teaches pg, neo4j-driver and fetch against ArcadeDB.

  • Prefer the clients you already have in Go — Go quickstart, which teaches pgx against ArcadeDB.

  • Already running a PostgreSQL stack — PostgreSQL wire protocol.

  • Already running a Neo4j stack — Neo4j BOLT.

  • Any other language — HTTP/JSON API, no driver required.

ArcadeDB publishes six native drivers, an HTTP one and a gRPC one for each of Python, JavaScript/TypeScript and Go, from the arcadedb-drivers repository. Every one of them is generated from a shared contract — an OpenAPI specification for the HTTP drivers, a Protobuf .proto for the gRPC drivers — and each driver’s build regenerates from that contract and fails if the checked-in code and a fresh regeneration disagree.

That matters to you, not just to the people who build the drivers: a generated client cannot silently disagree with the server about the wire format. When ArcadeDB adds a field, the driver gets it from the contract rather than from someone remembering to hand-write it.

HTTP or gRPC?

Choose When

HTTP

General application traffic, browsers, serverless functions, and anywhere you want the smallest dependency footprint. This is the right default.

gRPC

Throughput-sensitive server-to-server work: large result sets you want to stream rather than page, and bulk inserts.

There is no browser gRPC driver, and there cannot be one until the server changes. ArcadeDB’s GrpcServerPlugin is plain grpc-java over HTTP/2, with no gRPC-Web handler and no Connect protocol in front of it. A browser cannot speak raw HTTP/2 gRPC framing at all, so no client library in any language can reach this server from a browser. Use an HTTP driver there.

The result envelope, and why truncated matters

The HTTP drivers' query and command do not return bare rows. They return the whole response envelope: result, limit, returned, and truncated.

truncated is true when the server’s serializer hit its row cap while the query still had rows left to write. result is then a partial answer, not a short-but-complete one — and the two are indistinguishable by shape. A caller that reads result and ignores truncated will silently work off half an answer.

Always check truncated before treating result as the whole result set. When it is true, re-query with a narrower filter or a higher limit. Raising limit is not always the fix: a result whose true size exceeds the server’s hard ceiling (arcadedb.server.httpQueryMaxResultRows) is refused outright with HTTP 413 rather than truncated, so past that ceiling a narrower filter is the only way forward.

Versions and server compatibility

All six drivers are released together, at one version, and each release is generated against one ArcadeDB server release’s contract:

Driver version ArcadeDB server Packages

0.3.0

26.10.2

All six: arcadedb-driver and arcadedb-driver-grpc (PyPI), @arcadedb/driver and @arcadedb/driver-grpc (npm), github.com/ArcadeData/arcadedb-drivers/go/arcadedb and …​/go/arcadedbgrpc (Go modules)

0.2.0

26.10.1

All six

0.1.0

26.9.1

PyPI and npm only

Pointing a driver at a server on a materially different release may work for the endpoints both versions share, but is not tested or supported. Install commands in these pages are deliberately unpinned; the registries carry the current version. The Go modules had no 0.1.0 release: their first published version is 0.2.0. Each release’s changes are listed in the arcadedb-drivers release notes.

Upgrading to 0.3.0

0.3.0 adds server administration, login sessions and API tokens, listing and terminating running work, query tags, and a duplex insert session to the three HTTP drivers; each language’s page below shows them. Three changes can affect existing code:

  • gRPC insert streams no longer copy the database into InsertOptions.database. All three gRPC drivers send database on the first chunk only, as the .proto specifies. Every supported server (26.9.1 and later) reads it there. A server older than 26.9.1 reads only options.database, so against it a stream now reports its rows as received, inserts nothing, and raises no error. If you must use such a server, set options.database yourself.

  • A stream’s in-band error carries the server’s own status. An error event in the middle of an HTTP query or command stream used to surface with status 200. It now carries the event’s status (500, 503, 409 and so on), and falls back to 200 only when the event has none. Retry logic keyed on the status now sees the real one.

  • Go: the option types are split. QueryOption is now a sealed interface, joined by CommandOption and TransactionOption. Existing calls compile unchanged; only code that implemented QueryOption itself, or passed a []QueryOption to Command, needs updating.