Neo4j Driver Java Skill

# neo4j-driver-java-skill

Skill for writing Java (and Kotlin) code with the official Neo4j Java Driver v6.

**Covers:**
- Maven/Gradle dependency setup
- Driver creation, `verifyConnectivity`, lifecycle management
- `executableQuery` — recommended default API
- Managed transactions (`executeRead` / `executeWrite`) with result lifecycle rules
- Explicit transactions, rollback safety, commit uncertainty
- Async API (`CompletableFuture` / `CompletionStage`)
- Reactive API (Project Reactor `RxSession`)
- Error handling (`ServiceUnavailableException`, `TransientException`, `Neo4jException`)
- Data type mapping and null-safety (`asString`, `isNull`, `containsKey`)
- Batch writes with `UNWIND` and parameter type rules
- Connection pool tuning
- Causal consistency and cross-session bookmarks

**Compatibility:** Neo4j Java Driver v6 · Java 17+ · Kotlin 1.9+

**Not covered:**
- Cypher query authoring → `neo4j-cypher-skill`
- Driver version migrations → `neo4j-migration-skill`
- Spring Data Neo4j (`@Node`, `Neo4jRepository`) → `neo4j-spring-data-skill`

**Install:**
```bash
npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-driver-java-skill
```

Or paste into your coding assistant:
https://github.com/neo4j-contrib/neo4j-skills/tree/main/neo4j-driver-java-skill


# Advanced Configuration — Neo4j Java Driver

## Full `Config.builder()` options

```java
import org.neo4j.driver.Config;
import org.neo4j.driver.Logging;
import org.neo4j.driver.net.ServerAddress;
import org.neo4j.driver.NotificationConfig;
import org.neo4j.driver.NotificationSeverity;
import java.util.concurrent.TimeUnit;

var driver = GraphDatabase.driver(uri, auth,
    Config.builder()
        // Connection pool
        .withMaxConnectionPoolSize(50)                           // default: 100
        .withConnectionAcquisitionTimeout(30, TimeUnit.SECONDS) // wait for free conn
        .withMaxConnectionLifetime(1, TimeUnit.HOURS)
        .withConnectionLivenessCheckTimeout(30, TimeUnit.MINUTES)

        // Custom resolver — useful for local dev against a cluster
        .withResolver(address -> Set.of(ServerAddress.of("localhost", 7687)))

        // TLS
        .withEncryption()
        .withTrustStrategy(Config.TrustStrategy.trustAllCertificates()) // dev ONLY

        // Notification filtering — reduce noise in logs
        .withNotificationConfig(NotificationConfig.defaultConfig()
            .enableMinimumSeverity(NotificationSeverity.WARNING))

        // Logging
        .withLogging(Logging.slf4j())           // production
        // .withLogging(Logging.console(Level.DEBUG))  // debug

        // Record fetch size (controls Bolt batching)
        .withFetchSize(1000)                    // default: 1000

        .build());
```

## Session-level auth (multi-tenant)

Cheaper than a new `Driver` per tenant — reuses the connection pool:

```java
var session = driver.session(SessionConfig.builder()
    .withDatabase("tenant_db")
    .withAuthToken(AuthTokens.basic("tenant-user", "pass"))
    .build());
```

## User impersonation

Requires `IMPERSONATE` privilege on the executing user:

```java
var session = driver.session(SessionConfig.builder()
    .withDatabase("neo4j")
    .withImpersonatedUser("jane")
    .build());
```

## Connection pool diagnosis

| Error message | Cause | Fix |
|---|---|---|
| `Unable to acquire connection from the pool within configured maximum time` | Pool exhausted | Increase `maxConnectionPoolSize` or fix session leaks |
| `Connection to the database terminated` / `ServiceUnavailableException` | Network/server issue | Check server health, firewall, TLS |
| Session hangs with no error | Session leak — connection never returned | Add try-with-resources; audit all code paths |

## Spatial Types

```java
import org.neo4j.driver.Values;

// Create points — Values.point(srid, x, y) / Values.point(srid, x, y, z)
var cartesian2d = Values.point(7203,  1.23, 4.56);           // Cartesian 2D
var cartesian3d = Values.point(9157,  1.