Graphus v0.0.8

Graphus v0.0.8

Version: 0.0.8
Date: 2026-07-07
Tag: v0.0.8

Summary

Graphus v0.0.8 is a Bolt-protocol / connection-pool safety fix for Graphus, the Label
Property Graph (LPG) database server written in Rust for extreme load and concurrency. It restores
safe reuse of pooled connections after a statement error inside an explicit
BEGIN … COMMIT transaction — the exact pattern the official Neo4j drivers rely on when they run
managed transactions against a connection pool.

After any statement error inside an explicit transaction — even a trivial RETURN 1/0 — the Bolt
RESET failed to abort the executor's still-open transaction, so the connection was permanently
poisoned: every subsequent BEGIN on it failed with
Neo.TransientError.Transaction.Outdated ("a transaction is already open"). The root cause was a
state-machine gap: a statement failure moves the Bolt state machine to Failed, which erases the
TxReady / TxStreaming marker that RESET used to decide whether to roll back — so RESET
skipped the rollback in exactly the case where it was needed most. Because the official Neo4j
drivers reuse connections from a pool, one poisoned connection returned to the pool and failed the
work of other, unrelated sessions, so session.execute_write(...) could not converge under
contention. RESET now rolls back the executor's open transaction unconditionally, in
conformance with the Bolt RESET specification ("set the connection back to its initial state …
stopping any unit of work").

This is a drop-in upgrade from v0.0.7: the transaction, isolation, Cypher,
and data contracts are unchanged, and no new user-facing feature was added. The only behavioural
change is that RESET now reliably returns a connection to a clean READY state. ACID was never
at risk — no transaction ever committed partially and no data was lost; only connection reuse
after an in-transaction error was broken.

Throughout, the four inviolable guarantees held:

• 100% ACID — full transactional reliability under power loss, faults, and crashes.
• 100% openCypher TCK — 3914 / 3914 scenarios passing.
• 100% Bolt protocol — byte-for-byte interoperability with the Neo4j driver ecosystem.
• 100% PackStream — exact wire-level serialization.

Highlights

• Pooled connections survive an in-transaction error. After a statement fails inside an
  explicit BEGIN … COMMIT transaction, a RESET now aborts the underlying transaction and the
  connection is immediately reusable, instead of being permanently poisoned for every later BEGIN.
• No cross-session contamination. A single connection that hit an in-transaction error can no
  longer return to the driver's pool and fail the work of other, unrelated sessions.
• Managed retries converge under contention. With connections no longer poisoned by the
  serialization-conflict retries that v0.0.7 enabled,
  session.execute_write(...) now converges under contention as intended.
• Bolt RESET conformance restored. RESET returns the connection to a clean READY state
  unconditionally, matching the specification ("stopping any unit of work"), across every path that
  reaches the Failed state from inside a transaction.
• No ACID or data-contract change. Correctness was already intact; this release only fixes the
  connection-lifecycle handling of RESET.

Fixed

• A pooled Bolt connection was permanently poisoned after any error inside an explicit
  transaction (Bolt-protocol conformance / connection-pool safety). A statement failure inside an
  explicit BEGIN … COMMIT transaction moves the Bolt state machine to Failed (via fail_with),
  which erases the TxReady / TxStreaming marker. handle_reset gated its executor.rollback()
  on exactly that marker, so a RESET issued after an in-transaction error skipped the
  rollback: the executor's transaction leaked and the connection was left holding an open
  transaction it could no longer see. Every subsequent BEGIN on that connection then failed with
  Neo.TransientError.Transaction.Outdated ("a transaction is already open"). Because the official
  Neo4j drivers reuse connections from a pool, a single poisoned connection returned to the pool and
  failed the work of other, unrelated sessions, so session.execute_write(...) could not
  converge under contention. handle_reset now calls executor.rollback_open_tx()
  unconditionally — a method that consults the executor's own current_tx, is a no-op when
  nothing is open, and is idempotent and infallible — so RESET returns the connection to a clean
  READY regardless of the Bolt state enum. This covers every path into Failed from inside a
  transaction: a RUN error in TxReady, a runtime error during PULL / DISCARD, or an
  out-of-order message. ACID itself was never at risk: no partial commit and no lost data ever
  occurred — only connection reuse after an in-transaction error was broken.

Verification

This release was validated empirically; no functional test reported an error.

• Empirical, real-driver discovery. The defect was discovered and reproduced deterministically
  against the live server instance using the real neo4j Python driver 6.2.0: a plain
  RETURN 1/0 executed inside begin_transaction poisoned the connection, after which every
  managed execute_write(...) retry failed to converge under contention. This surfaced only after
  v0.0.7 enabled managed retry of serialization conflicts — the previous
  .Terminated poison-title behaviour made drivers discard the connection instead of reusing
  it, which masked the poisoning entirely.
• RED→GREEN regression coverage. A new graphus-bolt regression drives the exact failing
  sequence — BEGIN, RUN 1/0 (FAILURE), RESET, BEGIN — and asserts that the second
  BEGIN now succeeds (it was a FAILURE, "a transaction is already open", before the fix). The
  existing mid-transaction rollback test was updated to assert the RESET-triggered
  rollback_open_tx of the open transaction.
• Conformance gates intact. The openCypher TCK remains at 3914 / 3914 (100%), and the ACID,
  Bolt, and PackStream guarantees are unchanged. cargo test -p graphus-bolt is green, including
  the new regression, and cargo fmt is clean.

Compatibility

v0.0.8 is a drop-in upgrade from v0.0.7. The transaction and isolation model is exactly as in
v0.0.7 (MySQL-style autocommit reads at Snapshot Isolation, fully Serializable
writes and explicit BEGIN … COMMIT transactions; see
docs/transactions.md), and no new user-facing feature was added.

The only behavioural change is that a Bolt RESET now reliably rolls back an in-flight transaction
and returns the connection to a clean READY state, even when a previous statement failed inside
the transaction. No action is required — the official Neo4j drivers already issue a RESET
when returning a connection to their pool, so this fix takes effect transparently. Applications that
manually reuse a connection after an in-transaction error will simply find that the next BEGIN
now succeeds instead of failing with Neo.TransientError.Transaction.Outdated.

Upgrading

# Docker Hub (multi-arch: linux/amd64 + linux/arm64)
docker pull flaviocfo/graphus:v0.0.8             # or :latest

See docs/getting-started.md for first-run instructions,
docs/transactions.md for the read/write isolation model and how to retry
a serialization failure, and docs/bolt.md for the Bolt-over-TCP and
Bolt-over-UDS interfaces.