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

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