Skip to main content

Bolt

RushDB implements the server side of Bolt, the Neo4j binary protocol, so that Bolt clients can run Cypher against RushDB. This page covers enabling the listener, the handshake and messages RushDB supports, transactions, how values are encoded, and the limits of the implementation. It is for developers bringing Neo4j-style applications or tools to RushDB.

PropertyValue
StatusRelease candidate, opt-in (as openCypher)
Protocol versionBolt 5.0
LanguageopenCypher only
Authenticationbasic scheme; the credentials are the bootstrap token or a tenant-bound capability token
EncryptionTLS with --tls-cert/--tls-key (bolt+s://, neo4j+s://); plaintext otherwise

Note: No maintained Rust Neo4j driver negotiates Bolt 5, so the release suite verifies the wire protocol with a protocol-conformant Bolt 5 client (handshake, HELLO authentication, RUN/PULL reads and writes, BEGIN/COMMIT/ROLLBACK, and PackStream byte values). The official Python (neo4j 6.4) and JavaScript (neo4j-driver 6.2) drivers were checked by hand against the examples on this page; they are not part of the automated suite.

Enabling the listener​

The Bolt listener needs a port and a graph language:

Shell
rushdb serve --data-dir ./data --languages sql,cypher --bolt-port 7687

It binds only when --bolt-port is non-zero and cypher is enabled: statements over Bolt are always Cypher, so enabling only gql does not start the listener. The listener binds the --listen address and follows the listener security rules.

Tenants​

On a multitenant server each transaction runs in one tenant, named the way Neo4j names a database. A driver sends its session's database (database= in Python, { database } in JavaScript) as db in every BEGIN and every auto-commit RUN, so the tenant is chosen per transaction:

Where db isWhat it selects
BEGINThe tenant of the whole transaction: its RUNs, COMMIT and ROLLBACK. A RUN inside it that names a different db fails with Neo.ClientError.Request.Invalid.
auto-commit RUNThe tenant of that one statement.
ROUTEThe tenant the routing table is for, echoed as rt.db.
HELLOThe session's tenant: used by a BEGIN, RUN or ROUTE that names none. Drivers do not send it; hand-written clients may.

A db on BEGIN or RUN takes precedence over HELLO's, as Neo4j's per-transaction database does. An empty db or neo4j names no tenant.

Which tenants a session may name depends on its credential:

  • The bootstrap token may name any tenant, a different one per transaction on the same connection. When it names none anywhere, a statement fails with Neo.ClientError.Security.Unauthorized (scope is required in multitenant mode).
  • A capability token is bound to one tenant. It logs in without a db (as drivers do) to that tenant, which is then the session's tenant; naming it again is allowed. A BEGIN, RUN or ROUTE naming any other tenant fails with Neo.ClientError.Security.Forbidden and runs nothing.

On a single-tenant server, leave db unset (or neo4j): any other value, in HELLO, BEGIN or RUN, makes the statement fail with Neo.ClientError.Security.Unauthorized (scope_mismatch) instead of opening a second keyspace.

Connection flow​

  1. Handshake. The client sends the Bolt magic preamble and up to four version proposals. RushDB accepts the first proposal whose major version is 5 and answers with Bolt 5.0. If no proposal is version 5, the connection is closed.
  2. HELLO. Authenticate with scheme: "basic" and credentials set to the bootstrap token or a capability token (principal is ignored). An optional db names the session's tenant (see Tenants); a capability must be bound to exactly that tenant. scheme: "none" is accepted only when the server token is empty. A wrong credential returns Neo.ClientError.Security.Unauthorized. Any message other than HELLO or GOODBYE before successful authentication is refused, and a statement the capability does not grant (a write under read) fails with Neo.ClientError.Security.Forbidden. The server identifies itself as RushDB/1.0.
  3. RUN and PULL. RUN takes the Cypher text and an optional parameter map. RushDB decides from the statement's parsed plan whether it reads or writes, and routes it to the read or the write operation; you do not need separate read and write sessions. RUN executes the whole statement and buffers its rows; PULL {n} streams them in windows (n: -1 means all). has_more tells you whether rows remain. The SUCCESS that ends the result carries the query type (r, w, or rw for a write that returns rows) and, after a write that changed data, stats: {"contains-updates": true}. That is the only counter: RushDB reports how many changes a write applied, not of which kind, so a driver's nodes_created and similar counters stay 0 while contains_updates is true.
  4. GOODBYE closes the connection.

Supported messages:

MessageBehavior
HELLOAuthentication; optional db sets the session's tenant.
RUNExecute a Cypher statement (auto-commit, or staged inside BEGIN); db in extra names the auto-commit statement's tenant.
PULLStream buffered rows; honors n.
DISCARDDrop buffered rows; honors n.
BEGIN, COMMIT, ROLLBACKExplicit transactions; db in BEGIN's extra names the transaction's tenant.
RESETClear the pending result and recover from a failure.
ROUTEReturns a single-server routing table: --bolt-advertised-address (or the bound address) as the ROUTE, READ and WRITE server, with db set to the tenant extra.db names.
GOODBYEClose the connection.

Bolt 5.1+ messages (LOGON, LOGOFF, TELEMETRY) are not implemented; clients must authenticate with HELLO as in Bolt 5.0.

Transactions​

BEGIN opens a RushDB multi-request transaction, the same mechanism as the protocol's transaction operations. Each write RUN inside it stages the statement's changes; COMMIT publishes them atomically and ROLLBACK discards them. On a multitenant server, db in BEGIN names the tenant the whole transaction runs in (omit it on a single-tenant server).

Text
C: BEGIN {"db": "acme"}
S: SUCCESS {}
C: RUN "CREATE (p:Person {name: 'commit'})-[:WORKS_AT]->(:Company {name: 'Acme'})" {} {}
S: SUCCESS {"fields": [], "type": "w"}
C: PULL {"n": -1}
S: SUCCESS {"type": "w", "stats": {"contains-updates": true}, "has_more": false}
C: COMMIT
S: SUCCESS {}

Nodes, relationships (between new nodes, staged nodes or committed ones), updates and deletes all stage, so a driver's managed transactions (execute_write) work for any write.

Rules inside an explicit transaction:

  • A read statement (for example a plain MATCH ... RETURN) runs as an ordinary query against committed data, as queries do alongside a transaction on every transport (only getRecord reads through one). It does not see the transaction's own staged writes.
  • A write statement inside a transaction returns no rows.
  • RESET ends the open transaction and discards its staged changes.
  • The transaction is subject to the server's transaction limits (--tx-default-ttl-seconds, --tx-max-operations, --tx-max-staged-bytes) and may abort with Neo.TransientError.Transaction.DeadlockDetected when a concurrent commit conflicts. Retry the whole transaction.

See Transactions.

Values​

Parameters and results use the Bolt PackStream encoding, limited to JSON-like values:

Bolt typeSupport
Null, Boolean, Integer (64-bit), Float, Stringyes
List, Mapyes (up to 1,000,000 items per container, nesting depth 64)
Bytesno: a message containing bytes is rejected
Node, Relationship, Path structuresnot sent: nodes and relationships are returned as maps
Temporal and spatial structuresno

A returned node is a map of its properties plus __id (its dashed UUID) and __label; a relationship is a map of its properties plus __id, __type, __source_id, and __target_id (dashed UUIDs). Drivers that expect Node and Relationship objects see plain maps instead. Return properties (RETURN n.name AS name) when you need typed columns.

Using a Neo4j driver​

Connect with bolt://, or bolt+s:// / neo4j+s:// when the listener has TLS (+ssc for a self-signed certificate), and pass the server token or a capability token as the password; the user name is ignored. With neo4j:// or neo4j+s:// the driver follows the ROUTE answer, so set --bolt-advertised-address to the address it can reach. On a multitenant server, name the tenant as the session's database (database="acme"); a capability token may also leave it out to use its own tenant.

Python (pip install neo4j):

Python
from neo4j import GraphDatabase

driver = GraphDatabase.driver("bolt://127.0.0.1:7687", auth=("rushdb", "local-token"))
with driver.session() as session:
# Auto-commit queries: reads and writes both work.
session.run("CREATE (a:Artist {name: $name})", name="ada").consume()
for record in session.run("MATCH (a:Artist) RETURN a.name AS name"):
print(record["name"])

# A managed write transaction commits its writes atomically.
session.execute_write(lambda tx: tx.run("CREATE (:Artist {name: 'grace'})").consume())

# Managed read transactions and execute_query read committed data.
count = session.execute_read(lambda tx: tx.run("MATCH (a:Artist) RETURN count(a) AS n").single()["n"])

# Multitenant server: each session runs in the tenant it names.
with driver.session(database="acme") as session:
session.run("CREATE (:Artist {name: 'ada'})").consume()
driver.close()

JavaScript (npm install neo4j-driver):

JavaScript
import neo4j from 'neo4j-driver'

const driver = neo4j.driver('bolt://127.0.0.1:7687', neo4j.auth.basic('rushdb', 'local-token'))
const session = driver.session() // multitenant: driver.session({ database: 'acme' })
try {
await session.run('CREATE (a:Artist {name: $name})', { name: 'ada' })
const result = await session.run('MATCH (a:Artist) RETURN a.name AS name')
console.log(result.records.map((record) => record.get('name')))
} finally {
await session.close()
await driver.close()
}

What to expect from a driver:

  • Reads see committed data. Auto-commit session.run, the managed read transactions (execute_read, executeRead) and execute_query all work. A read inside execute_write/executeWrite does not see that transaction's own writes until it commits.
  • Nodes and relationships are maps. RETURN n gives a map with __id, __label and the properties, not a driver Node.
  • Integers are 64-bit. The JavaScript driver returns them as its Integer type; call .toNumber() or create the driver with { disableLosslessIntegers: true }.

Error codes​

Bolt failure codeEngine error codes
Neo.ClientError.Security.Unauthorizedunauthorized, missing_scope, scope_mismatch, failed HELLO
Neo.ClientError.Security.Forbiddenthe session's capability does not grant the statement, or a BEGIN/RUN/ROUTE names a tenant the capability is not bound to
Neo.ClientError.Statement.SyntaxErrorinvalid_request, protocol_violation, language_disabled, unsupported
Neo.ClientError.Statement.EntityNotFoundnot_found
Neo.ClientError.Constraint.UniqueConstraintViolationconflict
Neo.TransientError.Transaction.DeadlockDetectedwrite_conflict
Neo.ClientError.Transaction.TransactionTerminatedcancelled
Neo.TransientError.General.DatabaseUnavailableresource_exhausted, unavailable, or a result over 100,000 rows
Neo.ClientError.Request.Invalidunsupported_version, malformed PULL/DISCARD metadata, a RUN in a transaction naming another db
Neo.DatabaseError.Execution.Failedexecution_failed
Neo.ClientError.Transaction.TransactionNotFoundCOMMIT or ROLLBACK without BEGIN

After a failure, send RESET before continuing.

Limits​

LimitValue
Message size64 MiB
Rows buffered per RUN100,000; larger results fail. Page with SKIP/LIMIT.
Concurrent connections1,024
Time to authenticate after connecting10 seconds
Idle read/write timeout60 seconds

Not supported​

  • Cluster routing beyond a single-server table.
  • Languages other than Cypher over Bolt.
  • Vector, full-text, and native operations; use the HTTP API.

See also​