Saltearse al contenido

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ámetroValor
URIneo4j+s://db.namidb.com:7687 (o bolt+s://…)
Usuariocualquiera, se ignora (namidb en los ejemplos)
Contraseñatu API key (nmdb_live_…)
Base de datosel nombre de la base de datos; opcional cuando la key llega exactamente a una base de datos
ProtocoloBolt 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

Ventana de terminal
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();

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, withDatabase en Java, ExecuteQueryWithDatabase en 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ímiteFreeProScale
Sesiones Bolt abiertas por organización645122,048
Timeout de consulta10 s30 s60 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ónCódigo de Neo4j¿El driver reintenta?
Key inválida, revocada o vencidaNeo.ClientError.Security.Unauthorizedno
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.Forbiddenno
Límite de uso alcanzado, demasiadas sesionesun 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?

BoltHTTP
Ideal paraCódigo existente de Neo4j, servidores de larga duración, transacciones explícitasFunciones serverless y edge, scripts, cualquier lenguaje
ConexiónDe larga duración, en poolUna petición por sentencia
Log de consultas lentasSe registraSe registra

Ambos usan la misma key, los mismos límites y la misma medición.