hanamizuki/solopreneur/neo4j-migration

When to Use

• Upgrading driver dependency from 4.x or 5.x to 6.x
• Migrating Cypher queries to Cypher 25 syntax
• Fixing deprecated API warnings after a driver or Neo4j version bump
• Auditing a codebase for removed/deprecated Neo4j APIs before upgrading

When NOT to Use

• Writing new Cypher queries → neo4j-cypher-skill
• DB admin (backup, restore, import, cypher-shell) → neo4j-cli-tools-skill
• Starting fresh → neo4j-getting-started-skill
• GDS algorithm migration — not covered here; consult GDS release notes

Entry Criteria

Before starting, ask:

1. Target Neo4j version — needed to select Cypher dialect and driver version
2. Languages in use — scan package.json, requirements.txt, pom.xml, *.csproj, go.mod
3. Current driver versions — read from dependency files; do NOT guess

If target is >= 2025.06: ask whether Cypher 5 or Cypher 25 dialect will be used (both supported; Cypher 25 is the new default).

Step 1 — Scan Codebase

# Find Cypher strings (queries embedded in source)
grep -rn "MATCH\|MERGE\|CREATE\|CALL\|RETURN" --include="*.py" --include="*.js" \
  --include="*.ts" --include="*.java" --include="*.cs" --include="*.go" \
  --include="*.cypher" --include="*.cql" . | grep -v ".git"
 
# Find dependency files
find . -name "requirements*.txt" -o -name "package.json" -o -name "pom.xml" \
  -o -name "*.csproj" -o -name "go.mod" | grep -v ".git" | grep -v node_modules

Collect findings before modifying anything. List all deprecated patterns found.

Step 2 — Cypher Migration (4.x / 5.x → Cypher 25)

Apply to every Cypher string, .cypher file, OGM/SDN @Query annotation, and template literal.

Complete Substitution Table

Vector Index Queries (version-branched)

Cypher Dialect Prefix Rule

• Target >= 2025.06, dialect = Cypher 25: prepend CYPHER 25 to every top-level query
• Target >= 2025.06, dialect = Cypher 5: prepend CYPHER 5 (keeps deprecated forms working)
• Target 4.x or 5.x: no prefix needed; fetch changelog per references/cypher-queries.md

id(n) → elementId(n) Caveats

elementId() returns a string (e.g., "4:abc123:0"), not an integer. Fix downstream code that stores or compares it as int. Do NOT use elementId() values for numeric operations.

- WHERE id(n) = $nodeId   # $nodeId was integer
+ WHERE elementId(n) = $nodeId  # $nodeId must now be string

Step 3 — Driver Migration

Pick the section(s) matching languages found in Step 1.

Python Driver (5.x → 6.x)

Min requirements: Python >= 3.10, neo4j package (6.0+, released Jan 12 2026)

Package Rename — do this first

# requirements.txt
- neo4j-driver>=5.0.0
+ neo4j>=6.0.0

neo4j-driver package is deprecated since 6.0 and receives no further updates.

Removed APIs

Resource Management Change

Drivers and sessions no longer auto-close on GC. Add explicit cleanup:

- driver = GraphDatabase.driver(URI, auth=(USER, PASS))
- # used without explicit close
+ with GraphDatabase.driver(URI, auth=(USER, PASS)) as driver:
+     with driver.session(database="neo4j") as session:
+         ...

Or call .close() explicitly. Repeated .close() is a no-op.

Error Handling Changes

Key APIs Unchanged

execute_query(), GraphDatabase.driver(), neo4j+s:// URI, auth=(user, pw), session run().

Full changelog: references/python-driver.md

JavaScript / Node.js Driver (5.x → 6.x)

Min requirements: Node.js >= 18 (check engines in driver's package.json); package neo4j-driver

Removed APIs

Deprecated in 6.0 (will be removed in 7.0)

Integer Handling

Neo4j integers map to neo4j.Integer (64-bit). Use .toNumber() or .toInt() for arithmetic. Large values (> 2^53) lose precision — store as string with .toString().

// Safe pattern
const count = record.get('count').toNumber()

Full changelog: references/javascript-driver.md

Java Driver (5.x → 6.x)

Min requirements: Java 21; Maven org.neo4j.driver:neo4j-java-driver:6.x

Maven Coordinates

<dependency>
  <groupId>org.neo4j.driver</groupId>
  <artifactId>neo4j-java-driver</artifactId>
- <version>5.x.x</version>
+ <version>6.0.0</version>
</dependency>

Removed APIs

Dependency Note (BOM)

neo4j-java-driver-bom no longer imports netty-bom as of 6.0.1. If using Netty native transport, add explicit netty-bom import.

Logging

Legacy Logging API deprecated → configure System.Logger instead.

Full changelog: references/java-driver.md

.NET Driver (5.x → 6.x)

Min requirements: .NET 8, 9, or 10 (.NET Standard 2.1 dropped); NuGet Neo4j.Driver 6.x

NuGet Package

- <PackageReference Include="Neo4j.Driver" Version="5.*" />
+ <PackageReference Include="Neo4j.Driver" Version="6.*" />

Neo4j.Driver.Signed no longer receives updates — switch to Neo4j.Driver (now signed).

Removed APIs

Full changelog: references/dotnet-driver.md

Go Driver (5.x → 6.x)

Min requirements: Go 1.24; module github.com/neo4j/neo4j-go-driver/v6

go.mod Update

- require github.com/neo4j/neo4j-go-driver/v5 v5.x.x
+ require github.com/neo4j/neo4j-go-driver/v6 v6.x.x

Update all imports from /v5/ to /v6/.

Removed APIs and Replacements

Context API Consolidation

In v6, neo4j.NewDriverWithContext is the canonical constructor. The old *WithContext method names are deprecated (targeted for removal in v7) — base names now include context by default.

- driver, err := neo4j.NewDriver(uri, neo4j.BasicAuth(user, pass, ""))
+ driver, err := neo4j.NewDriverWithContext(uri, neo4j.BasicAuth(user, pass, ""))

Full migration guide: references/go-driver.md

Step 4 — Version Compatibility Matrix

Store format: no changes between 4.4 and 2026.x. block format default for new Enterprise dbs since 5.22. high_limit and standard deprecated in 5.23, removed after 2026 LTS.

No downgrades supported — take a backup before any server upgrade.

Step 5 — Test After Migration

# Python: run with dev mode to surface all deprecation warnings
python -W error::DeprecationWarning -m pytest tests/
 
# JS: run tests
npm test
 
# Java
mvn test
 
# .NET
dotnet test
 
# Go
go test ./...

After test run: if any DeprecationWarning or deprecated-API log appears, treat as ERROR — fix before proceeding.

For Cypher: run each migrated query through EXPLAIN first: