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.
| Setting | Value |
|---|---|
| URI | neo4j+s://db.namidb.com:7687 (or bolt+s://…) |
| Username | anything, it is ignored (namidb in the examples) |
| Password | your API key (nmdb_live_…) |
| Database | the database name; optional when the key reaches exactly one database |
| Protocol | Bolt 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
npm install neo4j-driverimport 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();pip install neo4jimport osfrom neo4j import GraphDatabase
auth = ("namidb", os.environ["NAMIDB_API_KEY"])with GraphDatabase.driver("neo4j+s://db.namidb.com:7687", auth=auth) as driver: records, summary, _ = driver.execute_query( "MATCH (m:Movie) RETURN m.title AS title LIMIT $n", n=5, database_="movies", ) print([r["title"] for r in records])Add org.neo4j.driver:neo4j-java-driver (any 5.x release) to your Maven or
Gradle build.
import java.util.Map;import org.neo4j.driver.AuthTokens;import org.neo4j.driver.GraphDatabase;import org.neo4j.driver.QueryConfig;
public class Movies { public static void main(String[] args) { var auth = AuthTokens.basic("namidb", System.getenv("NAMIDB_API_KEY")); try (var driver = GraphDatabase.driver("neo4j+s://db.namidb.com:7687", auth)) { var result = driver.executableQuery("MATCH (m:Movie) RETURN m.title AS title LIMIT $n") .withParameters(Map.of("n", 5)) .withConfig(QueryConfig.builder().withDatabase("movies").build()) .execute(); result.records().forEach(r -> System.out.println(r.get("title").asString())); } }}go get github.com/neo4j/neo4j-go-driver/v5package main
import ( "context" "fmt" "os"
"github.com/neo4j/neo4j-go-driver/v5/neo4j")
func main() { ctx := context.Background() auth := neo4j.BasicAuth("namidb", os.Getenv("NAMIDB_API_KEY"), "") driver, err := neo4j.NewDriverWithContext("neo4j+s://db.namidb.com:7687", auth) if err != nil { panic(err) } defer driver.Close(ctx)
result, err := neo4j.ExecuteQuery(ctx, driver, "MATCH (m:Movie) RETURN m.title AS title LIMIT $n", map[string]any{"n": 5}, neo4j.EagerResultTransformer, neo4j.ExecuteQueryWithDatabase("movies")) if err != nil { panic(err) } for _, record := range result.Records { title, _ := record.Get("title") fmt.Println(title) }}dotnet add package Neo4j.Driverusing Neo4j.Driver;
var auth = AuthTokens.Basic("namidb", Environment.GetEnvironmentVariable("NAMIDB_API_KEY"));await using var driver = GraphDatabase.Driver("neo4j+s://db.namidb.com:7687", auth);
var result = await driver .ExecutableQuery("MATCH (m:Movie) RETURN m.title AS title LIMIT $n") .WithParameters(new { n = 5 }) .WithConfig(new QueryConfig(database: "movies")) .ExecuteAsync();
foreach (var record in result.Result) Console.WriteLine(record["title"].As<string>());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,withDatabasein Java,ExecuteQueryWithDatabasein 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
| Limit | Free | Pro | Scale |
|---|---|---|---|
| Open Bolt sessions per organization | 64 | 512 | 2,048 |
| Query timeout | 10 s | 30 s | 60 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:
| Condition | Neo4j code | Driver retries? |
|---|---|---|
| Invalid, revoked or expired key | Neo.ClientError.Security.Unauthorized | no |
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.Forbidden | no |
| Rate limited, too many sessions | a Neo.TransientError.* code | yes |
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?
| Bolt | HTTP | |
|---|---|---|
| Best for | Existing Neo4j code, long-lived servers, explicit transactions | Serverless and edge functions, scripts, any language |
| Connection | Long-lived, pooled | One request per statement |
| Slow-query log | Recorded | Recorded |
Both use the same key, limits and metering.