Skip to content

Bolt and Neo4j drivers

NamiDB Cloud speaks Bolt, the protocol of the Neo4j drivers, so the official drivers and the tools built on them connect without changes.

SettingValue
URIneo4j+s://db.namidb.com:7687 (or bolt+s://…)
Usernameanything, it is ignored (namidb in the examples)
Passwordyour API key (nmdb_live_…)
Databasethe database name; optional when the key reaches exactly one database
ProtocolBolt 5.4 to 5.7, and 4.4 for older drivers

TLS is required: always use neo4j+s:// or bolt+s://. Both work; with neo4j+s:// the driver asks for a routing table and gets one pointing back at db.namidb.com.

Drivers

Terminal window
npm install neo4j-driver
import neo4j from 'neo4j-driver';
const driver = neo4j.driver(
'neo4j+s://db.namidb.com:7687',
neo4j.auth.basic('namidb', process.env.NAMIDB_API_KEY!),
);
const { records } = await driver.executeQuery(
'MATCH (m:Movie) RETURN m.title AS title LIMIT $n',
{ n: neo4j.int(5) },
{ database: 'movies' },
);
console.log(records.map((r) => r.get('title')));
await driver.close();

Any current release of the official drivers works (5.x, and 4.4 drivers through Bolt 4.4).

Choosing the database

  • Pass the database name as the driver’s database setting (database_= in Python, { database } in JavaScript, withDatabase in Java, ExecuteQueryWithDatabase in Go, QueryConfig(database:) in .NET), or per session.
  • When the key reaches exactly one database you may leave it out: that database is used.
  • When the key reaches several, always name it. A statement for a database outside the key’s scope fails with Neo.ClientError.Security.Forbidden.

Transactions

Auto-commit queries (executeQuery, session.run) run each statement on its own. Explicit transactions (executeWrite, executeRead, beginTransaction) work too:

  • A write transaction holds the database’s writer lock until it commits or rolls back, so keep write transactions short.
  • A read transaction (or any transaction on a read-only key) runs on a snapshot and never takes the writer lock.
  • Every statement has the plan’s query timeout (10 s / 30 s / 60 s on Free / Pro / Scale).
  • Access is checked again inside an open transaction. Revoking the key, or removing the client’s address from an IP allowlist, ends a transaction that is already open: it is rolled back, its locks are released, and the driver gets an error saying why on its next request.

Limits

LimitFreeProScale
Open Bolt sessions per organization645122,048
Query timeout10 s30 s60 s

Statements sent over Bolt count against the organization’s requests per second and concurrent queries, like HTTP requests. Each client address can hold up to 512 open connections. Connecting (handshake and authentication) must finish within 10 seconds. Use one driver instance per process and let it pool connections.

Errors

Refusals by NamiDB itself (before a statement reaches the engine) arrive as Bolt failures with Neo4j codes:

ConditionNeo4j codeDriver retries?
Invalid, revoked or expired keyNeo.ClientError.Security.Unauthorizedno
Read-only key wrote, database not in scope, plan limit, paused or suspended organization, address not on an IP allowlist, blocked for abuse (access_banned)Neo.ClientError.Security.Forbiddenno
Rate limited, too many sessionsa Neo.TransientError.* codeyes

After org_paused, org_suspended, ip_not_allowed or access_banned the connection is closed. The engine’s own errors (syntax, constraint violations, timeouts, query memory limits) are passed through unchanged: see Errors.

Types and tools

Values map to the drivers’ native types (Node, Relationship, Path, dates and times): see the type table on the self-hosted Bolt page. Tools built on the official drivers generally work for querying and browsing the schema (labels, relationship types, property keys, indexes and constraints). Neo4j administration features (users, dbms.* procedures, APOC) are not available.

Bolt or HTTP?

BoltHTTP
Best forExisting Neo4j code, long-lived servers, explicit transactionsServerless and edge functions, scripts, any language
ConnectionLong-lived, pooledOne request per statement
Slow-query logRecordedRecorded

Both use the same key, limits and metering.