From 3fea32c1ec3d1236ed0fa745298756592c2763f1 Mon Sep 17 00:00:00 2001 From: robfrank Date: Fri, 20 Nov 2026 19:32:05 +0100 Subject: [PATCH] docs(#12202): a standalone BEGIN, COMMIT or ROLLBACK outside a session is refused over HTTP and gRPC (#12232) --- src/main/asciidoc/reference/cypher/cypher-clauses.adoc | 2 +- src/main/asciidoc/reference/http-api/http.adoc | 8 ++++++++ 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/src/main/asciidoc/reference/cypher/cypher-clauses.adoc b/src/main/asciidoc/reference/cypher/cypher-clauses.adoc index ccca253e..194b60e5 100644 --- a/src/main/asciidoc/reference/cypher/cypher-clauses.adoc +++ b/src/main/asciidoc/reference/cypher/cypher-clauses.adoc @@ -2555,7 +2555,7 @@ ROLLBACK The optional `ISOLATION` clause is an ArcadeDB extension — GQL does not define isolation levels for `START TRANSACTION`. It accepts `READ_COMMITTED` (the default) or `REPEATABLE_READ`, matching the SQL `BEGIN ISOLATION` statement. -NOTE: To span multiple requests the transaction needs a stateful session. Over HTTP, pass a session id (the `arcadedb-session-id` header); over Bolt, the connection provides the session. Over stateless HTTP without a session each request runs in its own transaction. +NOTE: To span multiple requests the transaction needs a stateful session. Over HTTP, pass a session id (the `arcadedb-session-id` header); over Bolt, the connection provides the session. Over stateless HTTP without a session, and over gRPC outside a client transaction, each request runs in its own transaction, so `START TRANSACTION`, `COMMIT` and `ROLLBACK` sent there on their own are refused with a client error _(since v26.12.1; before, they were answered OK and did nothing)_. NOTE: `COMMIT` with no active transaction reports an error; `ROLLBACK` with no active transaction is a no-op. A second `START TRANSACTION` while one is already active opens a nested transaction (as with SQL `BEGIN`). The GQL access modes `READ ONLY` / `READ WRITE` are not implemented (ArcadeDB has no read-only transaction mode); `START TRANSACTION READ ONLY` reports a parse error. diff --git a/src/main/asciidoc/reference/http-api/http.adoc b/src/main/asciidoc/reference/http-api/http.adoc index 85e75a8a..721577f1 100644 --- a/src/main/asciidoc/reference/http-api/http.adoc +++ b/src/main/asciidoc/reference/http-api/http.adoc @@ -155,6 +155,14 @@ A session is created with the <> request and returns a sessio Use the session id in the request header of further commands you want to execute in the same transaction and request <> to commit the server side transaction or <> to rollback the changes. After a period of inactivity (default is 5 seconds, see <>), the server automatically rolls back and purges expired transactions. +A transaction-control statement sent to <> without a session id is refused with `400` +(`CommandSemanticException`): a SQL `BEGIN`, `COMMIT` or `ROLLBACK`, or an openCypher `START TRANSACTION`, `COMMIT` or +`ROLLBACK`, also behind `PROFILE` (and, in openCypher, `EXPLAIN`). Without a session each command runs in its own +transaction, so such a statement could not open or end anything: use `/begin`, `/commit` and `/rollback` with the session +id, or a single <> command that holds the whole block. Inside a session these +statements run as before. The gRPC API refuses them the same way (`INVALID_ARGUMENT`) outside a client transaction. +_(Since v26.12.1: before, they were answered OK and did nothing, so a later `ROLLBACK` undid none of the writes in between.)_ + If a request names a session id the server can no longer resolve - because it expired, or was already committed or rolled back - a *write* is refused with `404`, while a *read* still answers, running outside any transaction. A read that degraded this way says so: the response carries an `arcadedb-session-expired` header holding the id that could