Skip to content

v0.3.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 16 Oct 12:22
· 8 commits to main since this release
v0.3.0
aebfa54
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

All six ArcadeDB drivers ship together at 0.3.0: Go, Python and TypeScript, each with an HTTP and a gRPC client. They are generated against ArcadeDB server 26.10.2, the latest release, which supports every feature listed below.

Install

npm install @arcadedb/driver@0.3.0          # HTTP
npm install @arcadedb/driver-grpc@0.3.0     # gRPC
pip install arcadedb-driver==0.3.0          # HTTP
pip install arcadedb-driver-grpc==0.3.0     # gRPC
go get github.com/ArcadeData/arcadedb-drivers/go/arcadedb@v0.3.0       # HTTP
go get github.com/ArcadeData/arcadedb-drivers/go/arcadedbgrpc@v0.3.0   # gRPC

⚠️ Breaking changes

  • gRPC insertStream no longer copies the database into InsertOptions.database (#45, #103). All three gRPC clients now send the database on the first chunk only, as the .proto specifies, and leave your options untouched.
    • Every supported server (26.9.1 and later) reads the database from the chunk, so nothing changes there.
    • Servers older than 26.9.1: they read only options.database, so a stream now inserts nothing and raises no error. You get rows received but inserted=0. If you are stuck on such a server, set options.database yourself.
  • Errors in the middle of a stream now carry the server's real status (#117, #119). An error event during queryStream / query_stream / QueryStream (or the command version) used to surface as status 200. It now carries the event's own status, such as 500 or 503, and falls back to 200 only when the event has none. If your retry logic looks at the status, it now sees the real one.
  • Go: the option types are split (#119). QueryOption is now a sealed interface, joined by CommandOption and TransactionOption. Existing calls compile unchanged. You only need to change code that implemented QueryOption itself, or that kept options in a []QueryOption and passed it to Command.

New in the HTTP clients

Everything below is in all three languages, and in both the sync and async APIs in Python.

Server administration (#122)

  • Create and drop databases.
  • Users: create, update, drop and list.
  • Groups: save, delete and list.
  • serverCommand for any other server command, still with typed errors.
  • A duplicate user or database now gives a 409 (on 26.10.2 and later; older servers answer 403 and 400).
  • sqlscript is now a first-class query language (SQLScript in Go).

Login sessions and API tokens (#123)

  • login, loginAs, withToken and logout.
  • listSessions, plus API tokens: createAPIToken, listAPITokens and deleteAPIToken.
  • A multi-tenant application can log in once per user and then keep a client that holds only that user's token.

Running work (#124)

  • See what is running: listQueries (filter by database or tag) and listTransactions.
  • Stop it: terminateQuery, terminateQueriesByTag and terminateTransaction, each with an optional wait.
    • Every answer has a typed status: terminated, completed, terminating or not found.
    • isQueryTerminated / is_query_terminated / IsQueryTerminated tells you whether a request failed because it was terminated, as opposed to another error with the same 409 status.
  • Follow long maintenance operations with db.progress().

Query tags (#117)

  • Label a query, command, stream, batch load or whole transaction with queryTag / query_tag / WithQueryTag.
  • You can then list and terminate work by that tag.

Richer errors (#117)

  • ArcadeDBError gains retryAfter and commitIndex.
  • A rejected time-series write raises TimeSeriesWriteError, which reports how many samples were written and which types or keys were dropped.

Duplex insert session over /ws (#110)

  • db.insertSession() / db.insert_session() / db.InsertSession().
  • You see each batch's acknowledgement before deciding what to send next and whether to commit, which POST /api/v1/batch cannot do.
  • It can also join an open transaction.

EXPLAIN and PROFILE plans (#74)

  • Query results now carry explain and explainPlan, so a plan no longer looks like an empty result set.

PromQL label values (#125)

  • db.promql.labelValues / label_values / LabelValues, with an optional time range.
  • Pass "__name__" to list the time-series type names.
  • Thanks to @lextleo for the first version (#127).

New in the gRPC clients

  • Insert streams inside a transaction (#46). insertStream can run through a transaction handle in all three languages, so the inserted rows commit or roll back with the transaction.
  • Per-call metadata in Python (#28). Python's gRPC client now accepts per-call metadata on the twelve methods that were missing it.

Good to know

  • Behind a load balancer, running work is per server. listQueries and the terminate methods only see the server the client happened to reach. These commands are never forwarded to the cluster leader.
  • A just-started statement briefly shows no text. Right after a request is accepted, listQueries lists it with no language and with the request line (POST /api/v1/command/<db>) as its text. Both are filled in a moment later.
  • A commit after terminateTransaction still reports success. The server answers 204 even though the transaction's writes were rolled back. This is a server issue, reported as ArcadeData/arcadedb#10164; the READMEs warn about it.

Release process

  • npm packages are published with trusted publishing (OIDC). No long-lived token is involved any more (#97, #98).
  • Go module tags are pushed before the Go proxy is asked about them, which avoids the 25-minute delay that hit 0.2.0 (#97).
  • Release tags are protected against being moved or deleted.
  • Every .proto change is now checked with buf breaking in CI (#29, #102).
All pull requests in this release

Features and fixes

  • #103 feat(grpc)!: retire the InsertOptions.database mirror in all three gRPC clients (#45)
  • #106 feat(http): carry explain / explainPlan in QueryEnvelope (#74)
  • #111 land #28, #46 and #30 (per-call metadata in Python gRPC, insert streams in transactions)
  • #112 /ws duplex insert session (#110)
  • #119 adopt the 26.11.1-SNAPSHOT API additions in the HTTP clients (#117)
  • #126, #128, #130 server administration and sqlscript (#122) in Go, Python and TypeScript
  • #129, #132 a duplicate user or database is 409 (#122)
  • #131, #133, #134 login, logout, sessions and API tokens (#123) in Go, Python and TypeScript
  • #135, #136 PromQL label values (#125)
  • #137 list and terminate running queries and transactions, and poll progress (#124)

Docs

  • #101 fix a non-existent setting name and 1-based positional parameter examples

Release, CI and contract

  • #97 trusted publishing on npm; never query the Go proxy before the tag exists
  • #102 check every .proto change with buf breaking (#29)
  • #99, #113, #120, #121, #138 contract refreshes, ending on the released 26.10.2
  • #140 set version 0.3.0

Dependencies

  • #114, #115, #116 Dependabot updates (npm dev, GitHub Actions, uv dev)

Full changelog: v0.2.0...v0.3.0

Publish results

Package Registry Status Run
@arcadedb/driver npm published run
@arcadedb/driver-grpc npm published run
arcadedb-driver pypi published run
arcadedb-driver-grpc pypi published run
github.com/ArcadeData/arcadedb-drivers/go/arcadedb goproxy published run
github.com/ArcadeData/arcadedb-drivers/go/arcadedbgrpc goproxy published run

skipped: already on its registry. published (verified on registry): no result recorded this attempt, but the registry has the version. unknown: no result recorded and the registry did not confirm it, or a run dispatched whose outcome was not seen - check it before re-running failed jobs.

Contributors

lextleo
Assets 2
Loading