Skip to content

Bolt (Neo4j drivers)

namidb-server can speak the Bolt protocol, so the official Neo4j drivers (Python, JavaScript, Java, .NET, Go) and Bolt-based tools connect without changes. Bolt and HTTP share the same namespace, writer, tokens and TLS settings, so they never disagree.

Enable it

Terminal window
namidb-server --store "file:///var/lib/namidb?ns=prod" \
--auth-token "$NAMIDB_AUTH_TOKEN" \
--bolt-listen 0.0.0.0:7687

(NAMIDB_BOLT_LISTEN is the environment form.) Without the flag the server is HTTP-only.

Connect

from neo4j import GraphDatabase
driver = GraphDatabase.driver(
"bolt://localhost:7687",
auth=("namidb", NAMIDB_AUTH_TOKEN), # any user name; the token is the password
)
with driver.session() as s:
s.run("CREATE (:City {name: 'Lima'})").consume()
for record in s.run("MATCH (c:City) RETURN c.name AS name"):
print(record["name"]) # Lima
driver.close()
  • Use the bolt:// scheme (or bolt+s:// / bolt+ssc:// with TLS). neo4j:// asks for a routing table, which NamiDB does not serve; drivers then fail with “Failed to obtain connection towards ‘WRITE’ server”.
  • Authentication. Basic auth with any user name and the token as the password, or bearer auth (neo4j.bearer_auth(token)). Both resolve the token exactly as HTTP does, including JWTs when the jwt feature is enabled. A wrong token fails with Neo.ClientError.Security.Unauthorized.
  • Protocol versions. 5.7, 5.4, 5.0 and 4.4 are negotiated, preferring the newest the driver offers. From 5.7 on, failures carry GQLSTATUS metadata.
  • Server agent. The server announces itself as Neo4j/5.13.0 because official drivers and GUIs refuse servers that do not. Override it with NAMIDB_BOLT_SERVER_AGENT, for example NamiDB/3.3.0 for lenient clients.

Databases

Modesession(database=…)
Single-tenantIgnored; every session uses the namespace in --store.
Multi-tenantNames the namespace. Omitted means --default-namespace. A token scoped to other namespaces gets Neo.ClientError.Security.Forbidden.
with driver.session(database="acme") as s:
s.run("MATCH (i:Item) RETURN i.sku AS sku").value()

Transactions

Auto-commit (session.run(…)) runs each statement as its own transaction, like HTTP. Drivers can also group statements in an explicit transaction:

def add_city(tx, name):
tx.run("CREATE (:City {name: $name})", name=name)
return tx.run("MATCH (c:City) RETURN count(c) AS n").single()["n"]
with driver.session() as s:
total = s.execute_write(add_city, "Quito") # commits on return
names = s.execute_read(
lambda tx: tx.run("MATCH (c:City) RETURN c.name AS n ORDER BY n").value()
)
tx = s.begin_transaction()
tx.run("CREATE (:Draft)")
tx.rollback() # nothing is kept
  • Statements inside a transaction see the transaction’s earlier writes.
  • Write transactions hold the namespace’s writer lock until COMMIT or ROLLBACK. Keep them short. An idle transaction is rolled back after --bolt-tx-timeout (default 30s), and any transaction after NAMIDB_BOLT_MAX_TX_LIFETIME (default 5m).
  • Read transactions (execute_read, or a session opened in read access mode) run on the published snapshot and never take the writer lock.
  • In multi-tenant mode an explicit transaction is pinned to the database named when it began.
  • Each statement still has the server’s --query-timeout / --write-timeout budget.

Type mapping

CypherBolt / driver type (Python shown)
NULL, BOOLEAN, INTEGER, FLOAT, STRINGNone, bool, int, float, str
LIST, MAPlist, dict
VECTORlist of floats
BYTESbytes
DATEneo4j.time.Date
DATETIMEneo4j.time.DateTime without a time zone; the value is UTC
Nodeneo4j.graph.Node; element_id is the node’s UUID
Relationshipneo4j.graph.Relationship
Pathneo4j.graph.Path

Parameters map the same way in reverse; driver Date and DateTime parameters are accepted.

Errors and retries

Bolt failures use the same classification as HTTP: the Neo4j code is the neo4j_code column of the HTTP error table. Official drivers automatically retry Neo.TransientError.* (resource pressure, admission limits, memory_pressure) and nothing else. Timeouts, row caps and the per-query memory budget (query_memory_limit, as Neo.ClientError.Statement.ResourceLimitExceeded) are ClientErrors on purpose: a re-run would hit the same budget again.

Results

RUN returns the column names; rows are produced as PULL asks for them, so a driver’s fetch size bounds what is converted and sent at once. Write statements report counters in the result summary (result.consume().counters.nodes_created). EXPLAIN … returns the plan as plan rows.

A result that has not been pulled yet stays buffered in the session, and the statement keeps its working-memory budget and its share of the shared pool until the last row is pulled or the result is discarded, reset or closed. Consume or close results promptly, or other queries may get a retryable memory_pressure.

Limits

LimitDefaultSetting
Concurrent Bolt connections1024; extra connections are closedNAMIDB_BOLT_MAX_CONNECTIONS
Message size before authentication64 KiB (fixed)—
Message size after authentication64 MiB--bolt-max-message-bytes
Shared decode working-set budgethalf of --memory-max-bytes, else about 1 GiBNAMIDB_BOLT_MEMORY_BUDGET_BYTES
Partial message deadline120s from the first byteNAMIDB_BOLT_PARTIAL_MESSAGE_TIMEOUT
Handshake10 s—

Vector parameters cost about nine wire bytes per float, so the default message cap admits batches of roughly 2,000 1024-dimension embeddings. An oversized message fails with Neo.ClientError.Request.Invalid and the connection closes; split large parameter sets into batches. Small control messages (PULL, DISCARD, COMMIT, ROLLBACK, RESET, GOODBYE, LOGOFF) are always admitted so clients can drain results and recover under memory pressure.

Tools

Bolt clients that use the official drivers generally work for querying and for browsing the schema: NamiDB answers the introspection calls GUIs make (CALL db.labels(), db.relationshipTypes(), db.propertyKeys(), db.schema.visualization(), SHOW INDEXES, SHOW CONSTRAINTS). Neo4j administration features (users, dbms.* procedures, APOC) are not available.

Token rotation

HTTP and multi-tenant Bolt pick up a reloaded tokens file on the next request or statement. A single-tenant Bolt session keeps the principal it authenticated with, so revoking a token does not end live sessions; restart the server or drop the connections if a revocation must take effect immediately.