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
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"]) # Limadriver.close()- Use the
bolt://scheme (orbolt+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 thejwtfeature is enabled. A wrong token fails withNeo.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.0because official drivers and GUIs refuse servers that do not. Override it withNAMIDB_BOLT_SERVER_AGENT, for exampleNamiDB/3.3.0for lenient clients.
Databases
| Mode | session(database=…) |
|---|---|
| Single-tenant | Ignored; every session uses the namespace in --store. |
| Multi-tenant | Names 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
COMMITorROLLBACK. Keep them short. An idle transaction is rolled back after--bolt-tx-timeout(default30s), and any transaction afterNAMIDB_BOLT_MAX_TX_LIFETIME(default5m). - 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-timeoutbudget.
Type mapping
| Cypher | Bolt / driver type (Python shown) |
|---|---|
NULL, BOOLEAN, INTEGER, FLOAT, STRING | None, bool, int, float, str |
LIST, MAP | list, dict |
VECTOR | list of floats |
BYTES | bytes |
DATE | neo4j.time.Date |
DATETIME | neo4j.time.DateTime without a time zone; the value is UTC |
| Node | neo4j.graph.Node; element_id is the node’s UUID |
| Relationship | neo4j.graph.Relationship |
| Path | neo4j.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
| Limit | Default | Setting |
|---|---|---|
| Concurrent Bolt connections | 1024; extra connections are closed | NAMIDB_BOLT_MAX_CONNECTIONS |
| Message size before authentication | 64 KiB (fixed) | — |
| Message size after authentication | 64 MiB | --bolt-max-message-bytes |
| Shared decode working-set budget | half of --memory-max-bytes, else about 1 GiB | NAMIDB_BOLT_MEMORY_BUDGET_BYTES |
| Partial message deadline | 120s from the first byte | NAMIDB_BOLT_PARTIAL_MESSAGE_TIMEOUT |
| Handshake | 10 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.