neo4j-contrib 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 25to 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
| 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 |
|
TRUST_ALL_CERTIFICATES |
trusted_certificates=TrustAll() |
|
TRUST_SYSTEM_CA_SIGNED_CERTIFICATES |
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
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
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
.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
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
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 — version-branched Cypher changelog selection (4.x, 5.x, 2025.x)
- references/python-driver.md — Python changelog URLs, full version history
- references/javascript-driver.md — JS changelog URLs by version
- references/java-driver.md — Java changelog URLs by version
- references/dotnet-driver.md — .NET changelog URLs by version
- 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/
Checklist
- Target Neo4j version confirmed; Cypher dialect selected (Cypher 5 or 25)
- Dependency files scanned; all driver versions identified
- Cypher substitution table applied to every query in codebase
-
id(n)→elementId(n)and downstream int→string conversions fixed -
PERIODIC COMMIT→CALL IN TRANSACTIONSin all batch writes -
CALL { WITH x ... }→CALL (x) { ... }in all subqueries - Package renames done (Python:
neo4j-driver→neo4j) - Deprecated session methods replaced (
read_transaction/readTransaction→execute_read/executeRead) - Resource cleanup added where missing (Python: context managers or
.close()) - Bookmark API updated (
last_bookmark→last_bookmarks,Bookmark→Bookmarks) - Go imports updated from
/v5/to/v6/;neo4j.Config→config.Config - Java: Java 21 confirmed; RxSession usages removed
- .NET:
ILogger→INeo4jLogger;Neo4j.Driver.Signed→Neo4j.Driver - Tests pass with no DeprecationWarnings
-
EXPLAINrun on all migrated Cypher queries; no errors