neo4j-driver-dotnet-skill

When to Use

• Writing C# or .NET code connecting to Neo4j
• Setting up IDriver, DI registration, or session/transaction lifecycle
• Questions about ExecutableQuery, IResultCursor, async patterns, result mapping
• Debugging sessions, type mapping, null safety, or error handling in .NET

When NOT to Use

• Writing/optimizing Cypher queries → neo4j-cypher-skill
• Upgrading from older driver version → neo4j-migration-skill

---

Install

dotnet add package Neo4j.Driver

Package	Use
Neo4j.Driver	Async API — use this
Neo4j.Driver.Simple	Synchronous wrapper
Neo4j.Driver.Reactive	System.Reactive streams

---

Driver Lifecycle

IDriver — thread-safe, connection-pooled, expensive to create. Create one per application.

using Neo4j.Driver;

// URI schemes:
//   neo4j+s://xxx.databases.neo4j.io   — TLS + cluster routing (Aura)
//   neo4j://localhost                   — unencrypted + cluster routing
//   bolt+s://localhost:7687             — TLS + single instance
//   bolt://localhost:7687               — unencrypted + single instance

await using var driver = GraphDatabase.Driver(
    "neo4j+s://xxx.databases.neo4j.io",
    AuthTokens.Basic("neo4j", "password"));

await driver.VerifyConnectivityAsync();   // fail fast on startup

IDriver and IAsyncSession implement IAsyncDisposable — always await using, never plain using.

// ❌ Wrong — synchronous Dispose() may block thread pool
using var driver = GraphDatabase.Driver(uri, auth);

// ✅ Correct
await using var driver = GraphDatabase.Driver(uri, auth);

Auth options: AuthTokens.Basic(u, p) / AuthTokens.Bearer(token) / AuthTokens.Kerberos(ticket) / AuthTokens.None

---

Environment Variables

Load connection config from environment / appsettings.json — never hardcode credentials.

// appsettings.json
{
  "Neo4j": {
    "Uri": "neo4j+s://xxx.databases.neo4j.io",
    "User": "neo4j",
    "Password": "secret",
    "Database": "neo4j"
  }
}