Bolt (drivers de Neo4j)
namidb-server puede hablar el protocolo Bolt, así que los drivers
oficiales de Neo4j (Python, JavaScript, Java, .NET, Go) y las herramientas
basadas en Bolt se conectan sin cambios. Bolt y HTTP comparten el mismo
namespace, writer, tokens y configuración TLS, así que nunca discrepan.
Habilitarlo
namidb-server --store "file:///var/lib/namidb?ns=prod" \ --auth-token "$NAMIDB_AUTH_TOKEN" \ --bolt-listen 0.0.0.0:7687(NAMIDB_BOLT_LISTEN es la forma como variable de entorno.) Sin el flag, el
servidor es solo HTTP.
Conectarse
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()- Usa el esquema
bolt://(obolt+s:///bolt+ssc://con TLS).neo4j://pide una tabla de enrutamiento, que NamiDB no sirve; los drivers fallan entonces con “Failed to obtain connection towards ‘WRITE’ server”. - Autenticación. Basic auth con cualquier nombre de usuario y el token
como contraseña, o bearer auth (
neo4j.bearer_auth(token)). Ambas resuelven el token exactamente igual que HTTP, incluidos los JWT cuando la featurejwtestá habilitada. Un token incorrecto falla conNeo.ClientError.Security.Unauthorized. - Versiones del protocolo. Se negocian 5.7, 5.4, 5.0 y 4.4, prefiriendo la más nueva que ofrezca el driver. Desde 5.7, los fallos llevan metadatos GQLSTATUS.
- Server agent. El servidor se anuncia como
Neo4j/5.13.0porque los drivers oficiales y las GUIs rechazan los servidores que no lo hacen. Cámbialo conNAMIDB_BOLT_SERVER_AGENT, por ejemploNamiDB/3.3.0para clientes más permisivos.
Bases de datos
| Modo | session(database=…) |
|---|---|
| Single-tenant | Se ignora; cada sesión usa el namespace de --store. |
| Multi-tenant | Indica el namespace. Si se omite, se usa --default-namespace. Un token limitado a otros namespaces recibe Neo.ClientError.Security.Forbidden. |
with driver.session(database="acme") as s: s.run("MATCH (i:Item) RETURN i.sku AS sku").value()Transacciones
El auto-commit (session.run(…)) ejecuta cada sentencia como su propia
transacción, igual que HTTP. Los drivers también pueden agrupar sentencias
en una transacción explícita:
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- Las sentencias dentro de una transacción ven las escrituras anteriores de la transacción.
- Las transacciones de escritura mantienen el lock del writer del
namespace hasta el
COMMITo elROLLBACK. Mantenlas cortas. Una transacción inactiva se revierte después de--bolt-tx-timeout(por defecto30s), y cualquier transacción después deNAMIDB_BOLT_MAX_TX_LIFETIME(por defecto5m). - Las transacciones de lectura (
execute_read, o una sesión abierta en modo de acceso de lectura) se ejecutan sobre el snapshot publicado y nunca toman el lock del writer. - En modo multi-tenant, una transacción explícita queda fijada a la base de datos indicada cuando empezó.
- Cada sentencia sigue teniendo el presupuesto
--query-timeout/--write-timeoutdel servidor.
Mapeo de tipos
| Cypher | Tipo de Bolt / del driver (se muestra Python) |
|---|---|
NULL, BOOLEAN, INTEGER, FLOAT, STRING | None, bool, int, float, str |
LIST, MAP | list, dict |
VECTOR | lista de flotantes |
BYTES | bytes |
DATE | neo4j.time.Date |
DATETIME | neo4j.time.DateTime sin zona horaria; el valor está en UTC |
| Nodo | neo4j.graph.Node; element_id es el UUID del nodo |
| Relación | neo4j.graph.Relationship |
| Camino | neo4j.graph.Path |
Los parámetros se mapean igual en sentido inverso; se aceptan parámetros
Date y DateTime del driver.
Errores y reintentos
Los fallos de Bolt usan la misma clasificación que HTTP: el código de Neo4j
es la columna neo4j_code de la
tabla de errores HTTP. Los
drivers oficiales reintentan automáticamente Neo.TransientError.*
(presión de recursos, límites de admisión, memory_pressure) y nada más.
Los timeouts, los límites de filas y el presupuesto de memoria por consulta
(query_memory_limit, como Neo.ClientError.Statement.ResourceLimitExceeded)
son ClientError a propósito: volver a ejecutar chocaría otra vez con el
mismo presupuesto.
Resultados
RUN retorna los nombres de las columnas; las filas se producen a medida
que PULL las pide, así que el fetch size del driver limita lo que se
convierte y se envía de una vez. Las sentencias de escritura informan los
contadores en el resumen del resultado
(result.consume().counters.nodes_created). EXPLAIN … retorna el plan
como filas plan.
Un resultado que todavía no se pidió queda en el buffer de la sesión, y la
sentencia conserva su presupuesto de memoria de trabajo
y su parte del pool compartido hasta que se pide la última fila o el
resultado se descarta, se reinicia o se cierra. Consume o cierra los
resultados sin demora, o otras consultas pueden recibir un memory_pressure
reintentable.
Límites
| Límite | Por defecto | Ajuste |
|---|---|---|
| Conexiones Bolt concurrentes | 1024; las conexiones adicionales se cierran | NAMIDB_BOLT_MAX_CONNECTIONS |
| Tamaño de mensaje antes de autenticar | 64 KiB (fijo) | — |
| Tamaño de mensaje después de autenticar | 64 MiB | --bolt-max-message-bytes |
| Presupuesto compartido de memoria de decodificación | la mitad de --memory-max-bytes; si no, cerca de 1 GiB | NAMIDB_BOLT_MEMORY_BUDGET_BYTES |
| Plazo para un mensaje parcial | 120s desde el primer byte | NAMIDB_BOLT_PARTIAL_MESSAGE_TIMEOUT |
| Handshake | 10 s | — |
Los parámetros vectoriales cuestan unos nueve bytes de transmisión por
flotante, así que el tope de mensaje por defecto admite lotes de
aproximadamente 2.000 embeddings de 1024 dimensiones. Un mensaje demasiado
grande falla con Neo.ClientError.Request.Invalid y la conexión se cierra;
divide los conjuntos grandes de parámetros en lotes. Los mensajes de
control pequeños (PULL, DISCARD, COMMIT, ROLLBACK, RESET,
GOODBYE, LOGOFF) siempre se admiten para que los clientes puedan vaciar
resultados y recuperarse bajo presión de memoria.
Herramientas
Los clientes Bolt que usan los drivers oficiales generalmente funcionan para
consultar y para explorar el esquema: NamiDB responde las llamadas de
introspección que hacen las GUIs (CALL db.labels(),
db.relationshipTypes(), db.propertyKeys(),
db.schema.visualization(), SHOW INDEXES, SHOW CONSTRAINTS). Las
funciones de administración de Neo4j (usuarios, procedimientos dbms.*,
APOC) no están disponibles.
Rotación de tokens
HTTP y Bolt multi-tenant toman un archivo de tokens recargado en la siguiente petición o sentencia. Una sesión Bolt single-tenant conserva la identidad con la que se autenticó, así que revocar un token no termina las sesiones activas; reinicia el servidor o cierra las conexiones si una revocación debe aplicarse de inmediato.