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 h

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 Import: github.com/neo4j/neo4j go driver/v6/neo4j v5→v6 rename (deprecated aliases still compile, remove before v7): v5 v6 neo4j.NewDriverWithContext(...) neo4j.NewDriver(...) neo4j.DriverWithContext neo4j.Driver Environment Variables Use [godotenv](https://github.com/joho/godotenv) to load .env in dev: godotenv.Load() . .env in .gitignore . Driver Lifecycle One Driver per application. Goroutine safe, connection pooled, expensive to create. ❌ 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 API Use when Auto retry Lazy 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. Key options: ❌ 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 : Managed Transactions (Session Based) Use for lazy streaming (large result sets) or callback level control. ❌ No side effects in callback — retried on transient failures. ExecuteRead → replicas. ExecuteWrite → cluster leader. Explicit Transactions Use when transaction work spans multiple functions or requires external coordination. ❌ Not auto retried. Caller handles retry. Prefer managed transactions unless you need explicit control. Error Handling Helpers: In managed tx callback: return error → driver retries if transient. ConnectivityError at startup: check URI scheme, credentials, firewall. Data Types Cypher Go Integer int64 Float float64 String string Boolean bool List []any Map map[string]any Node neo4j.Node Relationship neo4j.Relationship Path neo4j.Path Date neo4j.Date DateTime neo4j.Time Duration neo4j.Duration UUID neo4j.UUID (= dbtype.UUID , [16]byte RFC 9562) — v6.2.0+, Bolt 6.1; parse with dbtype.ParseUUID(s) , render with .String() null nil ❌ Always check ok from record.Get() before type asserting — panics on missing key. ❌ After lazy for res.Next(ctx) loop, always check res.Err() . Key Patterns Context — always propagate context.Background() has no deadline — slow queries block indefinitely. Batching Writes Generic Helpers (v6+) Prefer type safe helpers over manual assertions: Spatial Types Always Specify Database Omitting costs a network round trip per call to resolve home database. Causal Consistency ExecuteQuery manages bookmarks automatically — no action needed for sequential calls. Cross session (parallel workers): combine bookmarks explicitly — see [references/repository pattern.md](references/repository pattern.md). Common Errors Error / Symptom Cause Fix ConnectivityError at startup URI wrong / TLS mismatch / firewall Check scheme ( neo4j+s:// for Aura), credentials, port 7687 ConnectivityError mid run Pool exhausted Increase MaxConnectionPoolSize ; check for leaked sessions Panic on type assertion record.Get() returned nil/wrong type Use neo4j.GetRecordValue[T]() or check ok first res.Err() non nil after loop Network error mid stream Handle error; re run transaction Callback retried unexpectedly Side effect inside managed tx Move side effects outside callback Context deadline exceeded No timeout on context Use context.WithTimeout 0 results, query looks correct Wrong DatabaseName Always set DatabaseName in config CALL IN TRANSACTIONS fails Run inside managed tx Use session.Run() (auto commit) References Load on demand: [references/advanced config.md](references/advanced config.md) — connection pool tuning, custom address resolver, notification config, Bolt logging, auth options, URI scheme table, deprecated result summary accessors ( Profile() → QueryProfile() ) [references/repository pattern.md](references/repository pattern.md) — repository wrapper pattern, cross session causal consistency with bookmarks WebFetch Need URL Go driver manual https://neo4j.com/docs/go manual/current/ API reference https://pkg.go.dev/github.com/neo4j/neo4j go driver/v6/neo4j Checklist [ ] One driver created at startup; shared across goroutines; defer driver.Close(ctx) [ ] driver.VerifyConnectivity(ctx) called at startup [ ] DatabaseName set in all SessionConfig / ExecuteQueryWithDatabase [ ] context.WithTimeout used for production queries [ ] map[string]any parameters used — no string interpolation [ ] ExecuteQueryWithReadersRouting() on read only ExecuteQuery calls [ ] res.Err() checked after lazy for result.Next(ctx) loop [ ] Type assertions guarded (use GetRecordValue[T] or check ok ) [ ] No side effects inside managed transaction callbacks [ ] session.Run() used for CALL IN TRANSACTIONS / auto commit queries [ ] Sessions closed with defer session.Close(ctx)

neo4j-driver-go-skill