neo4j-migration-skill

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:

Target Neo4j version — needed to select Cypher dialect and driver version
Languages in use — scan package.json, requirements.txt, pom.xml, *.csproj, go.mod
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

Old syntax	Cypher 25 replacement	Notes
`[:REL*1..5]`	`(()-[:REL]->()){1,5}`	QPE quantifier group
`[:REL*]`	`(()-[:REL]->()){1,}`	Unbounded QPE
`[:REL*0..5]`	`(()-[:REL]->()){0,5}`	Zero-hop allowed
`shortestPath((a)-[*]->(b))`	`SHORTEST 1 (a)(()-[]->()){1,}(b)`	QPE shortest path
`allShortestPaths((a)-[*]->(b))`	`ALL SHORTEST (a)(()-[]->()){1,}(b)`	QPE all-shortest
`id(n)`	`elementId(n)`	Returns string, not int
`CALL { WITH x ... }`	`CALL (x) { ... }`	Explicit import syntax
`PERIODIC COMMIT`	`CALL (...) { ... } IN TRANSACTIONS OF 1000 ROWS`	Batched writes
`-- comment`	`// comment`	SQL comment invalid
`SET n = r` (structural val)	`SET n = properties(r)`	Extract map first
`MERGE (a {x:1})-[:T]->(b {x:a.x})`	Rewrite — cross-entity MERGE refs disallowed	Split into MATCH+MERGE
`CREATE INDEX ... OPTIONS { indexProvider: ... }`	Remove `indexProvider` from OPTIONS	Provider selection removed
`db.create.setVectorProperty(...)`	Use native VECTOR property type	Procedure removed
`dbms.upgrade()` / `dbms.upgradeStatus()`	Use `cypher-shell :sysinfo`	Procedures removed
`USE composite.'1'`	` `USE` composite.1 `	Backtick entire qualified name
`RETURN 1 as my$Identifier`	` `RETURN 1 as` my$Identifier `	`$` removed from unescaped ids

Vector Index Queries (version-branched)

Version	Syntax
Neo4j < 2026.01	`CALL db.index.vector.queryNodes(idx, k, $emb) YIELD node, score`
Neo4j >= 2026.01	`SEARCH n IN (VECTOR INDEX idx FOR $emb LIMIT k) SCORE AS score`

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](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

Old	New	Notes
`session.read_transaction(fn)`	`session.execute_read(fn)`
`session.write_transaction(fn)`	`session.execute_write(fn)`
`session.last_bookmark()`	`session.last_bookmarks()`	Returns `Bookmarks` (plural)
`Bookmark` class	`Bookmarks` class
`TRUSTALLCERTIFICATES`	`trusted_certificates=TrustAll()`
`TRUSTSYSTEMCASIGNEDCERTIFICATES`	`trusted_certificates=TrustSystemCAs()`
`neo4j.conf`, `neo4j.data` modules	Removed — use top-level `neo4j.*`

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

Old exception	New exception	Trigger
`ClientError` (for timeout)	`ConnectionAcquisitionTimeoutError`	Acquisition timeout
`AuthError` (invalid config)	`ConfigurationError`	Invalid auth params
`ValueError` raised for `Query` obj	`TypeError`	Passing `Query` to `Transaction.run`

Key APIs Unchanged

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

Full changelog: [references/python-driver.md](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

Old	New	Notes
`session.readTransaction(fn)`	`session.executeRead(fn)`
`session.writeTransaction(fn)`	`session.executeWrite(fn)`
`session.lastBookmark()`	`session.lastBookmarks()`	Returns array
`resultSummary.updateStatistics`	`resultSummary.counters`
`driver.verifyConnectivity()` → `ServerInfo`	`driver.getServerInfo()` → `ServerInfo`	`verifyConnectivity()` now returns `void`

Deprecated in 6.0 (will be removed in 7.0)

Old	New
`isRetriableError(err)`	`isRetryable(err)`
`neo4jError.retriable`	`neo4jError.retryable`
`notificationCategory`	`notificationClassification`

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](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

Removed	Replacement	Notes
`RxSession` / `RxTransaction`	Use async `AsyncSession` or sync `Session`	Reactive API removed
`Bookmark` multi-value constructor	`Bookmark.from(iterable)`
`session.readTransaction(fn)`	`session.executeRead(fn)`
`session.writeTransaction(fn)`	`session.executeWrite(fn)`
`TrustStrategy.certFile()`	`TrustStrategy.trustCustomCertificateSignedBy(path)`
`Notification.severity()`	`Notification.severityLevel()`	Returns typed enum

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](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

Removed	Replacement	Notes
`ILogger`	`INeo4jLogger`	Interface renamed
`ConfigBuilder.WithIpv6Enabled()`	Remove call — IPv6 always enabled
`Config.Ipv6Enabled` property	Remove — always true
Simple driver	Use standard `IDriver`	Removed entirely

Full changelog: [references/dotnet-driver.md](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

Old	New	Notes
`neo4j.NewDriver(...)`	`neo4j.NewDriverWithContext(...)`	Context-aware; or just use `neo4j.NewDriver` (now has context)
`neo4j.Config` struct	`config.Config`	Import `github.com/neo4j/neo4j-go-driver/v6/neo4j/config`
`neo4j.ServerAddressResolver`	`config.ServerAddressResolver`
`neo4j.LogLevel` / `neo4j.ERROR` etc.	`log.Level` / `log.ERROR`	Import `neo4j/log` sub-package
`log.Console`	`log.ToConsole`
`log.Void`	`log.ToVoid`
`neo4j.Single[T]`	`neo4j.SingleT[T]` (still present; context variant preferred)
`neo4j.Driver` interface	`neo4j.DriverWithContext`	`*WithContext` variants are now primary
`neo4j.Session` interface	`neo4j.SessionWithContext`
`Config.RootCAs` field	`Config.TlsConfig`	Pass `*tls.Config` directly
Notification constants (old pkg)	`notifications.*` equivalents	Import `neo4j/notifications`

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](references/go-driver.md)

Step 4 — Version Compatibility Matrix

Neo4j version	Cypher dialect	Driver 6.x compatible	Notes
4.4 LTS	Cypher 4	Yes (bolt compat)	Support ended Nov 2025
5.26 LTS	Cypher 5	Yes	Supported until Nov 2028
2025.01–2025.05	Cypher 5	Yes	CalVer era begins
2025.06+	Cypher 5 or 25	Yes	Cypher 25 new default
2026.01+	Cypher 25	Yes	`SEARCH` clause available
2026.07.0	Cypher 25	Yes	Skip this patch — block-format UTF-8 regression makes `trim()` fail queries and corrupt stored strings; upgrade target is 2026.07.1

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:

# Via Query API v2
curl -X POST https://<host>/db/<database>/query/v2 \
  -u <user>:<password> -H "Content-Type: application/json" \
  -d '{"statement": "EXPLAIN <your query>"}'

Common Migration Errors

Error	Cause	Fix
`id(n)` returns string, int comparison fails	`elementId()` returns string	Update stored IDs to string; fix WHERE clauses
`Cannot merge node using null property value`	MERGE key resolved to null	Validate params before MERGE
`Neo4j.Driver.Exceptions.AuthenticationException`	Wrong credential config after .NET rename	Update `INeo4jLogger` usage; verify config
`TypeError: neo4j-driver is deprecated`	Old package installed	Replace with `neo4j>=6.0.0` in requirements
`AttributeError: 'Session' has no 'read_transaction'`	Python 5→6, method removed	Replace with `execute_read()`
`RxSession not found`	Java 6.x, Reactive API removed	Migrate to async or sync session
`undefined is not a function (.readTransaction)`	JS 6.x, method removed	Replace with `executeRead()`
Go: `undefined: neo4j.Config`	v5 import path still present	Update all imports to `/v6/`
`PERIODIC COMMIT not supported`	Cypher 25, clause removed	Use `CALL (...) IN TRANSACTIONS`
`Unknown function id()`	id() removed in Cypher 25	Replace with `elementId()`

References

Load on demand — high discovery rate because explicitly linked:

[references/cypher-queries.md](references/cypher-queries.md) — version-branched Cypher changelog selection (4.x, 5.x, 2025.x)
[references/python-driver.md](references/python-driver.md) — Python changelog URLs, full version history
[references/javascript-driver.md](references/javascript-driver.md) — JS changelog URLs by version
[references/java-driver.md](references/java-driver.md) — Java changelog URLs by version
[references/dotnet-driver.md](references/dotnet-driver.md) — .NET changelog URLs by version
[references/go-driver.md](references/go-driver.md) — Go migration guide with 5.0 and 6.0 sections

For any syntax not covered above, fetch: https://neo4j.com/docs/cypher-manual/25/deprecations-additions-removals-compatibility/

Installation

Similar popular skills

Also in this package

Agent compatibility

Also listed on

Repository health

Skill metadata

Package contents

History

SKILL.md

When to Use

When NOT to Use

Entry Criteria

Step 1 — Scan Codebase

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

Complete Substitution Table

Vector Index Queries (version-branched)

Cypher Dialect Prefix Rule

id(n) → elementId(n) Caveats

Step 3 — Driver Migration

Python Driver (5.x → 6.x)

Package Rename — do this first

Removed APIs

Resource Management Change

Error Handling Changes

Key APIs Unchanged

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

Removed APIs

Deprecated in 6.0 (will be removed in 7.0)

Integer Handling

Java Driver (5.x → 6.x)

Maven Coordinates

Removed APIs

Dependency Note (BOM)

Logging

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

NuGet Package

Removed APIs

Go Driver (5.x → 6.x)

go.mod Update

Removed APIs and Replacements

Context API Consolidation

Step 4 — Version Compatibility Matrix

Step 5 — Test After Migration

Common Migration Errors

References

Checklist

`id(n)` → `elementId(n)` Caveats