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

neo4j-driver-go-skill

Covers the Neo4j Go Driver v6 — driver lifecycle, ExecuteQuery, managed and

neo4j-contrib · 已有静态检查记录

安装与使用

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

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

技能说明


name: neo4j-driver-go-skill description: Covers the Neo4j Go Driver v6 — driver lifecycle, ExecuteQuery, managed and explicit transactions, session config, error handling, data type mapping, and connection tuning. Use when writing Go code that connects to Neo4j, setting up NewDriver or ExecuteQuery, debugging sessions/transactions/result handling, or working with neo4j-go-driver v5→v6 migration. Triggers on NewDriver, ExecuteQuery, SessionConfig, ManagedTransaction, neo4j-go-driver. Does NOT handle Cypher query authoring — use neo4j-cypher-skill. Does NOT cover driver version migration steps — use neo4j-migration-skill. version: 1.0.7 allowed-tools: Bash WebFetch

When to Use

  • Writing Go code that connects to Neo4j
  • Setting up neo4j.NewDriver(), ExecuteQuery(), or session/transaction patterns
  • Debugging connection errors, result iteration, type assertions, causal consistency

When NOT to Use

  • Writing/optimizing Cypher → neo4j-cypher-skill
  • v5→v6 migration steps → neo4j-migration-skill

Installation

go get github.com/neo4j/neo4j-go-driver/v6

Import: github.com/neo4j/neo4j-go-driver/v6/neo4j

v5→v6 rename (deprecated aliases still compile, remove before v7):

v5v6
neo4j.NewDriverWithContext(...)neo4j.NewDriver(...)
neo4j.DriverWithContextneo4j.Driver

Environment Variables

import "os"

uri      := getEnv("NEO4J_URI",      "neo4j://localhost:7687")
user     := getEnv("NEO4J_USERNAME", "neo4j")
password := getEnv("NEO4J_PASSWORD", "")
database := getEnv("NEO4J_DATABASE", "neo4j")

func getEnv(key, fallback string) string {
    if v := os.Getenv(key); v != "" { return v }
    return fallback
}

Use godotenv to load .env in dev: godotenv.Load(). .env in .gitignore.


Driver Lifecycle

One Driver per application. Goroutine-safe, connection-pooled, expensive to create.

func NewNeo4jDriver(uri, user, password string) (neo4j.Driver, error) {
    driver, err := neo4j.NewDriver(
        uri, // "neo4j+s://xxx.databases.neo4j.io" for Aura
        neo4j.BasicAuth(user, password, ""),
    )
    if err != nil {
        return nil, fmt.Errorf("create driver: %w", err)
    }
    ctx := context.Background()
    if err := driver.VerifyConnectivity(ctx); err != nil {
        driver.Close(ctx)
        return nil, fmt.Errorf("verify connectivity: %w", err)
    }
    return driver, nil
}

// In main / app teardown:
defer driver.Close(ctx)

❌ Never create driver per-request. Create once at startup; share across goroutines.

URI schemes: neo4j+s:// (Aura/TLS+routing), neo4j:// (plain+routing), bolt+s:// (TLS+single), bolt:// (plain+single).


Choosing the Right API

APIUse whenAuto-retryLazy results
neo4j.ExecuteQuery()Most queries — simple default✅❌ eager
session.ExecuteRead/Write()Large result sets / streaming✅✅
session.BeginTransaction()Spans multiple functions / ext coordination❌✅
session.Run()CALL IN TRANSACTIONS / auto-commit only❌✅

CALL { … } IN TRANSACTIONS and USING PERIODIC COMMIT manage their own transactions — use session.Run(). They fail inside managed transactions.


ExecuteQuery (Recommended Default)

Manages sessions, transactions, retries, and bookmarks automatically.

result, err := neo4j.ExecuteQuery(ctx, driver,
    `MATCH (p:Person {name: $name})-[:KNOWS]->(friend)
     RETURN friend.name AS name`,
    map[string]any{"name": "Alice"},
    neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("neo4j"),       // always specify
    neo4j.ExecuteQueryWithReadersRouting(),         // for read queries
)
if err != nil {
    return fmt.Errorf("query people: %w", err)
}

for _, record := range result.Records {
    name, _ := record.Get("name")
    fmt.Println(name)
}
fmt.Println(result.Summary.Counters().NodesCreated())

Key options:

neo4j.ExecuteQueryWithDatabase("mydb")          // required for performance
neo4j.ExecuteQueryWithReadersRouting()           // route reads to replicas
neo4j.ExecuteQueryWithImpersonatedUser("jane")  // impersonate
neo4j.ExecuteQueryWithoutBookmarkManager()       // opt out of causal consistency

❌ Never concatenate user input into query strings. Always use map[string]any parameters.

Struct parameters [v6.2.0+, Object Mapping preview] — a struct (or pointer) in params is sent as a Cypher map; same rules in Session.Run, ManagedTransaction.Run, ExplicitTransaction.Run:

type Person struct {
    Name     string `neo4j:"name"`
    Age      int    `neo4j:"age,omitempty"`  // zero value dropped
    Internal string `neo4j:"-"`              // never sent
}
_, err := neo4j.ExecuteQuery(ctx, driver,
    "MERGE (p:Person {name: $person.name}) SET p += $person",
    map[string]any{"person": Person{Name: "Alice", Age: 30}},
    neo4j.EagerResultTransformer,
    neo4j.ExecuteQueryWithDatabase("neo4j"),
)

Managed Transactions (Session-Based)

Use for lazy streaming (large result sets) or callback-level control.

session := driver.NewSession(ctx, neo4j.SessionConfig{
    DatabaseName: "neo4j", // always specify
    AccessMode:   neo4j.AccessModeRead,
})
defer session.Close(ctx)

result, err := session.ExecuteRead(ctx,
    func(tx neo4j.ManagedTransaction) (any, error) {
        res, err := tx.Run(ctx,
            `MATCH (p:Person) RETURN p.name AS name LIMIT $limit`,
            map[string]any{"limit": 100},
        )
        if err != nil {
            return nil, err
        }
        var names []string
        for res.Next(ctx) { // lazy — don't Collect() on large sets
            name, _ := res.Record().Get("name")
            names = append(names, name.(string))
        }
        return names, res.Err()
    },
)

❌ No side effects in callback — retried on transient failu

阅读完整来源 ↗