Neo4j migration skill

This skill uses online guides to upgrade old Neo4j codebases and Cypher queries. It handles all official Neo4j drivers and Cypher syntax migration.

When to use

Use this skill when:

a user asks to upgrade a Neo4j driver in languages: .NET, Go, Java, Javascript, Python
a user wants to upgrade Cypher queries from 4.x or 5.x syntax to 2025.x/2026.x (Cypher 25)

When NOT to use this skill

Writing new Cypher queries → use neo4j-cypher-skill
Database administration or CLI tasks (backup, restore, import, cypher-shell) → use neo4j-cli-tools-skill
Starting a new Neo4j project from scratch → use neo4j-getting-started-skill

Instructions

1. At the beginning, ALWAYS ask a user what Neo4j version is going to be used after the upgrade. Note, the Neo4j database's version is not upgraded as part of this skill, we just need that information a) If the user says that most recent, fetch the version from the supported version list along with the most recent driver version b) Otherwise, analyze the supported versions list and choose the most recent driver version for given Neo4j version

2. Analyze the codebase in order to determine what additional documentation to include, focus only on dependencies' files (e.g. package.json, requirements.txt, pom.xml etc.). If the codebase uses Neo4j driver for:

.NET then include .NET migration guide
Go then include Go migration guide
Java then include Java migration guide
Javascript/Node.JS then include Javascript migration guide
Python then include Python migration guide

Important: when you plan the upgrade, always include replacement of deprecated functions in the plan

---

Cypher Query Migration (4.x / 5.x → Cypher 25)

1. Ask the user what target Neo4j version will be used after the upgrade 2. Scan the codebase for Cypher query strings (look in .cypher files, string literals in driver code, OGM/SDN @Query annotations, etc.) 3. Apply these substitutions to every query found:

Old syntax	Cypher 25 replacement
`[:REL*1..5]`	`-[:REL]-{1,5}`
`[:REL*]`	`-[:REL]-{1,}`
`shortestPath((a)-[*]->(b))`	`SHORTEST 1 (a)(()-[]->()){1,}(b)`
`allShortestPaths((a)-[*]->(b))`	`ALL SHORTEST (a)(()-[]->()){1,}(b)`
`id(n)`	`elementId(n)`
`CALL { WITH x ... }`	`CALL (x) { ... }`
`-- SQL comment`	`// Cypher comment`
`CALL db.index.vector.queryNodes(...)`	`SEARCH n IN (VECTOR INDEX idx FOR $emb LIMIT k) SCORE AS score` (2026.01+; keep procedure for older)

4. Prepend CYPHER 25 to every query 5. Fetch the migration guide for any syntax not covered above: https://neo4j.com/docs/cypher-manual/25/deprecations-additions-removals-compatibility/

Language: .NET Upgrade versions: >= 1.7 Package: https://www.nuget.org/packages/Neo4j.Driver

Upgrade paths

Upgrading from version 1.7

If you're upgrading from version 1.7, first run the upgrade to version 4.0 by following this guide

Upgrading from versions >= 4.0

Important: Do not ever start upgrading the codebase before collecting all changelogs between the current, and the requested version

Check the changelog between the major versions by following these links:

4.1 changelog
4.2 changelog
4.3 changelog
4.4 changelog
every other major version changelog URL follows this pattern: https://raw.githubusercontent.com/wiki/neo4j/neo4j-dotnet-driver/{MAJOR_VERSION}.X-Change-Log.md where {MAJOR_VERSION} should be replaced with the major version you check the changelog for. E.g. for version 6.1 you'd fetch URL https://raw.githubusercontent.com/wiki/neo4j/neo4j-dotnet-driver/6.X-Change-Log.md . Do not replace the .x part of the URL

Language: Go Upgrade versions: >= 1.0 Package: https://github.com/neo4j/neo4j-go-driver

Upgrade paths

Important: Do not ever start upgrading the codebase before collecting all changelogs between the current, and the requested version

Upgrading from version 1.7

If you're upgrading from version 1.7, run the upgrade by following this guide

Upgrading from versions >= 4.0

To plan the upgrade from versions >= 4.0, you don't need to read the whole changelog, but only starting from "## 5.0 breaking changes" header

Upgrading from versions >= 5.0

To plan the upgrade from versions >= 5.0, you don't need to read the whole changelog, but only starting from "## 6.0 breaking changes" header

Language: Java Upgrade versions: >= 1.0 Package: https://central.sonatype.com/artifact/org.neo4j.driver/neo4j-java-driver

Upgrade paths

Important: Before performing the upgrade, make sure that the new version of the driver is compatible with Java version used in the project

Upgrading

Important: Do not ever start upgrading the codebase before collecting all changelogs between the current, and the requested version

Check the changelog between the major versions by following these links:

4.4 changelog
every other major version changelog URL follows this pattern: https://raw.githubusercontent.com/wiki/neo4j/neo4j-java-driver/{MAJOR_VERSION}.x-changelog.md where {MAJOR_VERSION} should be replaced with the version you check the changelog for. E.g. for version 6.1 you'd fetch URL https://raw.githubusercontent.com/wiki/neo4j/neo4j-java-driver/6.x-changelog.md . Do not replace the .x part of the URL

Language: Javascript/Node.JS Upgrade versions: >= 1.0 Package: https://www.npmjs.com/package/neo4j

Upgrade paths

Important: Do not ever start upgrading the codebase before collecting all changelogs between the current, and the requested version

Upgrading

Check the changelog between the major versions by following these links:

changelogs for versions <= 5.0 follow this pattern: https://raw.githubusercontent.com/wiki/neo4j/neo4j-javascript-driver/{VERSION}-changelog.md where {VERSION} should be replaced with both major and minor version number. E.g. for version 4.1 you'd fetch URL https://raw.githubusercontent.com/wiki/neo4j/neo4j-javascript-driver/4.1-changelog.md. Version numbers that can be accessed that way are: 1.0,1.1,1.2,1.3,1.4,4.0,4.1,4.2,4.3,4.4,5.0
every other major version changelog URL follows this pattern: https://raw.githubusercontent.com/wiki/neo4j/neo4j-javascript-driver/{MAJOR_VERSION}.x-changelog.md where {MAJOR_VERSION} should be replaced with the major version you check the changelog for. E.g. for version 6.1 you'd fetch URL https://raw.githubusercontent.com/wiki/neo4j/neo4j-javascript-driver/6.x-changelog.md . Do not replace the .x part of the URL

Language: Python Upgrade versions: >= 1.7 Package: https://pypi.org/project/neo4j/

Driver's package name change

The driver's package name has changed from neo4j-driver to neo4j. If the project is using the former, it needs to be changed before any actions performed

Upgrade paths

Upgrading from version 1.7

If you're upgrading from version 1.7, first run the upgrade to version 4.0 by following this guide

Upgrading from versions >= 4.0

Important: Do not ever start upgrading the codebase before collecting all changelogs between the current, and the requested version

Check the changelog between the major versions by following these links:

4.1 changelog
4.2 changelog
4.3 changelog
4.4 changelog
every other major version changelog URL follows this pattern: https://raw.githubusercontent.com/wiki/neo4j/neo4j-python-driver/{MAJOR_VERSION}.x-Changelog.md where {MAJOR_VERSION} should be replaced with the major version you check the changelog for. E.g. for version 6.1 you'd fetch URL https://raw.githubusercontent.com/wiki/neo4j/neo4j-python-driver/6.x-Changelog.md . Do not replace the .x part of the URL

Installs	78
repo stars	★ 101
Last updated	August 3, 2026
Repository	neo4j-contrib/neo4j-skills ↗

Neo4j Migration Skill

About