Skip to content
NamiDB NamiDB

Bolt (Neo4j drivers)

NamiDB speaks the Bolt protocol over an opt-in TCP listener on namidb-server. Every official Neo4j driver (Python, Java, JavaScript, .NET, Go, Rust) connects unmodified through bolt://host:7687.

The wire-level design lives in RFC-022; the codec, handshake and state machine live in the namidb-bolt crate.

Negotiated versions

  • Bolt 4.4
  • Bolt 5.0
  • Bolt 5.4

The handshake (0x6060B017 magic + four version offers, with the range form supported) advertises all three; the driver picks the highest it supports.

Enable the listener

Terminal window
namidb-server \
  --store memory://demo \
  --listen 0.0.0.0:8080 \
  --bolt-listen 0.0.0.0:7687 \
  --auth-token "$NAMIDB_AUTH_TOKEN"

--bolt-listen is also available as NAMIDB_BOLT_LISTEN. Both the HTTP API and the Bolt listener share one WriterSession per process and the same --auth-token.

Connect from a Neo4j driver

The username is the literal string namidb; the password is the same bearer token as the HTTP API. The credentials surface matches what every Neo4j driver expects.

from neo4j import GraphDatabase


driver = GraphDatabase.driver(
    "bolt://localhost:7687",
    auth=("namidb", "$NAMIDB_AUTH_TOKEN"),
)


with driver.session() as s:
    s.run("CREATE (:Person {name: 'Alice'})")
    for record in s.run("MATCH (p:Person) RETURN p.name AS name"):
        print(record["name"])

The same shape works with the other official Neo4j drivers — the connection string and the username / password tuple are the only NamiDB-specific bits.

Supported message vocabulary

namidb-bolt implements the full v4.4 / v5.0 / v5.4 request and response vocabulary: HELLO, LOGON, LOGOFF, RUN, PULL, DISCARD, BEGIN, COMMIT, ROLLBACK, RESET, ROUTE, TELEMETRY, GOODBYE.

The value mapping is a total RuntimeValue ↔ Bolt Value translation, including:

  • Node, Relationship, UnboundRelationship, Path.
  • Date, LocalDateTime — datetime() / date() from a driver round-trip back as the driver’s native types (e.g. neo4j.time.DateTime, neo4j.time.Date in Python). This is the fix landed in [Unreleased] that closed the __overflow_json loss-of-typing for undeclared Date / DateTime properties.

Concurrency

The Bolt listener shares the WriterSession with the HTTP API. The single-writer-per-namespace invariant still holds: at most one write statement is in flight against the namespace at a time. Reads share the same snapshot cell that RFC-021 publishes.

Test it end to end

The repo ships a manual smoke script (tests/bolt_neo4j_driver_smoke.py) that drives the official neo4j PyPI driver against a running namidb-server and verifies a CREATE / MATCH round-trip.

The integration test crates/namidb-server/tests/bolt_integration.rs runs the same flow against an in-process server through the Bolt 5.4 handshake.

What’s next

  • HTTP server — the daemon that hosts the Bolt listener.
  • HTTP API — the REST surface that shares the same WriterSession and auth.
  • Configuration — NAMIDB_BOLT_LISTEN and friends.