Neo4j Driver Go Skill

# neo4j-driver-go-skill

Skill for writing Go code with the Neo4j Go Driver v6.

## What this skill covers

- Driver setup, lifecycle, and connection verification
- `neo4j.ExecuteQuery` — the recommended default for most queries
- Managed transactions (`session.ExecuteRead/Write`) for lazy streaming
- Explicit transactions (`session.BeginTransaction`) for multi-function coordination
- Error handling (`Neo4jError`, `ConnectivityError`, retry behavior)
- Data type mapping (Go ↔ Cypher) and safe record extraction
- Context propagation and timeout patterns
- Batch write pattern with `UNWIND`
- Causal consistency and bookmark management

## Version / compatibility

- Neo4j Go Driver **v6** (current stable)
- Go >= 1.21 recommended
- v5 aliases still compile in v6; migrate before v7

## Not covered

- **Cypher query authoring** → `neo4j-cypher-skill`
- **v5→v6 migration steps** → `neo4j-migration-skill`
- Advanced connection pool tuning → `references/advanced-config.md`
- Repository wrapper pattern → `references/repository-pattern.md`

## Install

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


# Advanced Driver Configuration

## Connection Pool

```go
import "github.com/neo4j/neo4j-go-driver/v6/neo4j/config"

driver, _ := neo4j.NewDriver(uri, auth,
    func(conf *config.Config) {
        conf.MaxConnectionPoolSize = 50              // default: 100
        conf.ConnectionAcquisitionTimeout = 30 * time.Second
        conf.MaxConnectionLifetime = 1 * time.Hour
    },
)
```

## Custom Address Resolver + Notifications + Logging

```go
import (
    "github.com/neo4j/neo4j-go-driver/v6/neo4j/config"
    "github.com/neo4j/neo4j-go-driver/v6/neo4j/notifications"
)

driver, err := neo4j.NewDriver(uri, auth,
    func(conf *config.Config) {
        // Custom address resolver (e.g. local dev against a cluster)
        conf.AddressResolver = func(addr config.ServerAddress) []config.ServerAddress {
            return []config.ServerAddress{
                neo4j.NewServerAddress("localhost", "7687"),
            }
        }

        // Reduce notification noise
        conf.NotificationsMinSeverity = notifications.WarningLevel
        conf.NotificationsDisabledClassifications = notifications.DisableClassifications(
            notifications.Hint, notifications.Generic,
        )

        // Bolt-level debug logging
        conf.Log = neo4j.ConsoleLogger(neo4j.DEBUG)
    },
)
```

## Auth Options

```go
neo4j.BasicAuth(user, password, "")           // username + password
neo4j.BearerAuth(token)                        // SSO / JWT
neo4j.KerberosAuth(base64EncodedTicket)        // Kerberos
neo4j.NoAuth()                                 // unauthenticated (dev only)
```

## URI Schemes

| Scheme | When to use |
|--------|-------------|
| `neo4j://` | Unencrypted, cluster-routing |
| `neo4j+s://` | Encrypted (TLS), cluster-routing — use for Aura |
| `bolt://` | Unencrypted, single instance |
| `bolt+s://` | Encrypted, single instance |


# Repository Pattern — Wrapping the Driver

Wrap the driver behind a repository interface for testability and clean separation:

```go
type PersonRepo struct {
    driver neo4j.Driver
    db     string
}

func NewPersonRepo(driver neo4j.Driver, db string) *PersonRepo {
    return &PersonRepo{driver: driver, db: db}
}

func (r *PersonRepo) FindByName(ctx context.Context, name string) ([]Person, error) {
    result, err := neo4j.ExecuteQuery(ctx, r.driver,
        `MATCH (p:Person {name: $name}) RETURN p`,
        map[string]any{"name": name},
        neo4j.EagerResultTransformer,
        neo4j.ExecuteQueryWithDatabase(r.db),
        neo4j.ExecuteQueryWithReadersRouting(),
    )
    if err != nil {
        return nil, fmt.Errorf("find person %q: %w", name, err)
    }

    people := make([]Person, 0, len(result.Records))
    for _, rec := range result.Records {
        raw, _ := rec.Get("p")
        node := raw.(neo4j.Node)
        people = append(people, Person{
            Name: node.Props["name"].(string),