跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

neo4j-driver-javascript-skill

Neo4j JavaScript/TypeScript Driver v6 — driver lifecycle, executeQuery,

neo4j-contrib · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add neo4j-contrib/neo4j-skills --skill neo4j-driver-javascript-skill

技能说明


name: neo4j-driver-javascript-skill description: Neo4j JavaScript/TypeScript Driver v6 — driver lifecycle, executeQuery, managed transactions (executeRead/executeWrite), session.run, Integer handling, JSON serialization, record access, async/await patterns, TypeScript types, error handling, and connection setup for Node.js and browser. Use when writing JS/TS code that connects to Neo4j — neo4j.driver(), executeQuery, executeRead, executeWrite, session.run, neo4j.int, record.get, Integer, BookmarkManager, bolt://, neo4j+s://. Does NOT handle Cypher query authoring — use neo4j-cypher-skill. Does NOT cover driver version migration — use neo4j-migration-skill. compatibility: neo4j-driver v6; Node.js >=18; TypeScript supported via bundled types version: 1.0.5 allowed-tools: Bash WebFetch

When to Use

  • Writing JS/TS code that connects to Neo4j (Node.js or browser)
  • Setting up driver, sessions, transactions, or query execution
  • Debugging Integer handling, result consumption, session leaks, async errors
  • TypeScript type annotations for driver objects

When NOT to Use

  • Writing/optimizing Cypher → neo4j-cypher-skill
  • Upgrading driver version → neo4j-migration-skill
  • RxJS session API → references/rxjs-session.md

Install

npm install neo4j-driver   # or: yarn add neo4j-driver

Environment Variables

Load connection config from environment — never hardcode credentials.

# .env file (add to .gitignore)
NEO4J_URI=neo4j+s://xxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=secret
NEO4J_DATABASE=neo4j
// npm install dotenv (for Node.js < 20 or when .env auto-load is off)
import 'dotenv/config'   // or: require('dotenv').config()

const URI      = process.env.NEO4J_URI
const USER     = process.env.NEO4J_USERNAME
const PASSWORD = process.env.NEO4J_PASSWORD
const DATABASE = process.env.NEO4J_DATABASE ?? 'neo4j'

Node 20+ natively loads .env with --env-file .env. Next.js / Vite auto-load .env — no dotenv import needed.


Driver Lifecycle

Create one driver instance at startup. Share everywhere. Never create per-request.

// CommonJS
const neo4j = require('neo4j-driver')
// ESM / TypeScript
import neo4j from 'neo4j-driver'

const driver = neo4j.driver(
  process.env.NEO4J_URI,                              // 'neo4j+s://xxx.databases.neo4j.io'
  neo4j.auth.basic(process.env.NEO4J_USER, process.env.NEO4J_PASSWORD)
)
await driver.verifyConnectivity()   // fail fast on startup if unreachable
// On shutdown:
await driver.close()

URI schemes:

SchemeTransportUse
neo4j+s://TLS + cluster routingAura; production clusters
neo4j://plaintext + cluster routinglocal dev cluster
bolt+s://TLS, single instancesingle Neo4j instance with TLS
bolt://plaintext, single instancelocal single instance

Auth options:

neo4j.auth.basic(user, password)   // username/password
neo4j.auth.bearer(token)           // SSO / JWT
neo4j.auth.kerberos(base64Ticket)  // Kerberos
neo4j.auth.none()                  // unauthenticated (dev only)

Singleton for web frameworks — create once, import everywhere:

// db.js
let _driver = null
export function getDriver() {
  if (!_driver) _driver = neo4j.driver(process.env.NEO4J_URI,
    neo4j.auth.basic(process.env.NEO4J_USER, process.env.NEO4J_PASSWORD))
  return _driver
}
export async function closeDriver() {
  if (_driver) { await _driver.close(); _driver = null }
}

Serverless (Lambda/Vercel/Workers): keep maxConnectionPoolSize: 5; no guaranteed SIGTERM.


Choose the Right API

APIUse whenAuto-retryResult
driver.executeQuery()Default for most queries✅eager (all records)
session.executeRead/Write()Large results, streaming, multi-query tx✅lazy stream
session.run()LOAD CSV, CALL IN TRANSACTIONS, scripts❌lazy stream

executeQuery — Default

const { records, summary, keys } = await driver.executeQuery(
  'MATCH (p:Person {name: $name})-[:KNOWS]->(f) RETURN f.name AS name',
  { name: 'Alice' },
  { database: 'neo4j', routing: neo4j.routing.READ }
)
for (const record of records) {
  console.log(record.get('name'))   // use .get() — records are NOT plain objects
}

// Write and count results
const { summary: s } = await driver.executeQuery(
  'CREATE (p:Person {name: $name, age: $age})',
  { name: 'Bob', age: neo4j.int(30) },
  { database: 'neo4j' }
)
console.log(s.counters.updates().nodesCreated)   // ✅ must call .updates()

Always specify database — omitting causes an extra round-trip.

❌ Never template-literal Cypher:

// ❌ injection risk + disables plan caching
await driver.executeQuery(`MATCH (p:Person {name: '${name}'}) RETURN p`)
// ✅ parameterised
await driver.executeQuery('MATCH (p:Person {name: $name}) RETURN p', { name })

Managed Transactions (executeRead / executeWrite)

Auto-retried on transient failures. Consume records inside the callback — the stream is gone when the callback returns.

const session = driver.session({ database: 'neo4j' })
try {
  const names = await session.executeRead(async tx => {
    const result = await tx.run(
      'MATCH (p:Person) WHERE p.name STARTS WITH $prefix RETURN p.name AS name',
      { prefix: 'Al' }
    )
    // ✅ collect() while tx is open; return plain data
    return (await result.collect()).map(r => r.get('name'))
  })

  await session.executeWrite(async tx => {
    await tx.run('MERGE (p:Person {name: $name})', { name: 'Carol' })
  })
} finally {
  await session.close()   // always in finally
}

Critical: await tx.run() returns a stream handle, not records.

// ❌ returns stream; tx closes; records = []
return await tx.run('MATCH (p:Person) RETURN p.name AS name'
阅读完整来源 ↗