Bolt y drivers de Neo4j
NamiDB Cloud habla Bolt, el protocolo de los drivers de Neo4j, así que los drivers oficiales y las herramientas construidas sobre ellos se conectan sin cambios.
| Parámetro | Valor |
|---|---|
| URI | neo4j+s://db.namidb.com:7687 (o bolt+s://…) |
| Usuario | cualquiera, se ignora (namidb en los ejemplos) |
| Contraseña | tu API key (nmdb_live_…) |
| Base de datos | el nombre de la base de datos; opcional cuando la key llega exactamente a una base de datos |
| Protocolo | Bolt 5.4 a 5.7, y 4.4 para drivers más antiguos |
TLS es obligatorio: usa siempre neo4j+s:// o bolt+s://. Ambos funcionan;
con neo4j+s:// el driver pide una tabla de routing y recibe una que apunta de
vuelta a 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])Agrega org.neo4j.driver:neo4j-java-driver (cualquier versión 5.x) a tu build
de Maven o Gradle.
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>());Cualquier versión actual de los drivers oficiales funciona (5.x, y los drivers 4.4 mediante Bolt 4.4).
Elegir la base de datos
- Pasa el nombre de la base de datos en la opción de base de datos del driver
(
database_=en Python,{ database }en JavaScript,withDatabaseen Java,ExecuteQueryWithDatabaseen Go,QueryConfig(database:)en .NET), o por sesión. - Cuando la key llega a exactamente una base de datos puedes omitirlo: se usa esa base de datos.
- Cuando la key llega a varias, nómbrala siempre. Una sentencia para una base
de datos fuera del alcance de la key falla con
Neo.ClientError.Security.Forbidden.
Transacciones
Las consultas auto-commit (executeQuery, session.run) ejecutan cada
sentencia por separado. Las transacciones explícitas (executeWrite,
executeRead, beginTransaction) también funcionan:
- Una transacción de escritura retiene el lock de escritura de la base de datos hasta que hace commit o rollback, así que mantén cortas las transacciones de escritura.
- Una transacción de lectura (o cualquier transacción con una key de solo lectura) se ejecuta sobre un snapshot y nunca toma el lock de escritura.
- Cada sentencia tiene el timeout de consulta del plan (10 s / 30 s / 60 s en Free / Pro / Scale).
- El acceso se vuelve a comprobar dentro de una transacción abierta. Revocar la key, o quitar la dirección del cliente de una IP allowlist, termina una transacción que ya está abierta: se revierte, se liberan sus bloqueos y el driver recibe un error que explica el motivo en su siguiente petición.
Límites
| Límite | Free | Pro | Scale |
|---|---|---|---|
| Sesiones Bolt abiertas por organización | 64 | 512 | 2,048 |
| Timeout de consulta | 10 s | 30 s | 60 s |
Las sentencias enviadas por Bolt cuentan contra las peticiones por segundo y las consultas concurrentes de la organización, igual que las peticiones HTTP. Cada dirección de cliente puede mantener hasta 512 conexiones abiertas. La conexión (handshake y autenticación) debe completarse en 10 segundos. Usa una instancia del driver por proceso y deja que gestione el pool de conexiones.
Errores
Los rechazos del propio NamiDB (antes de que una sentencia llegue al motor) llegan como fallos de Bolt con códigos de Neo4j:
| Condición | Código de Neo4j | ¿El driver reintenta? |
|---|---|---|
| Key inválida, revocada o vencida | Neo.ClientError.Security.Unauthorized | no |
Una key de solo lectura escribió, base de datos fuera de alcance, límite del plan, organización pausada o suspendida, dirección fuera de una IP allowlist, bloqueo por abuso (access_banned) | Neo.ClientError.Security.Forbidden | no |
| Límite de uso alcanzado, demasiadas sesiones | un código Neo.TransientError.* | sí |
Después de org_paused, org_suspended, ip_not_allowed o access_banned
la conexión se cierra. Los errores propios del motor (sintaxis, violaciones de constraints,
timeouts, límites de memoria de las consultas) se transmiten sin cambios: consulta Errores.
Tipos y herramientas
Los valores se mapean a los tipos nativos de los drivers (Node,
Relationship, Path, fechas y horas): consulta la tabla de tipos en la
página de Bolt de self-hosted. Las
herramientas construidas sobre los drivers oficiales en general funcionan para
consultar y explorar el esquema (labels, tipos de relación, claves de
propiedades, índices y constraints). Las funciones de administración de Neo4j
(usuarios, procedimientos dbms.*, APOC) no están disponibles.
¿Bolt o HTTP?
| Bolt | HTTP | |
|---|---|---|
| Ideal para | Código existente de Neo4j, servidores de larga duración, transacciones explícitas | Funciones serverless y edge, scripts, cualquier lenguaje |
| Conexión | De larga duración, en pool | Una petición por sentencia |
| Log de consultas lentas | Se registra | Se registra |
Ambos usan la misma key, los mismos límites y la misma medición.