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:
| Scheme | Transport | Use |
|---|---|---|
neo4j+s:// | TLS + cluster routing | Aura; production clusters |
neo4j:// | plaintext + cluster routing | local dev cluster |
bolt+s:// | TLS, single instance | single Neo4j instance with TLS |
bolt:// | plaintext, single instance | local 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
| API | Use when | Auto-retry | Result |
|---|---|---|---|
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'
阅读完整来源 ↗