neo4j-migration-skill

适用场景

• 将驱动依赖从 4.x 或 5.x 升级到 6.x
• 将 Cypher 查询迁移到 Cypher 25 语法
• 升级驱动或 Neo4j 版本后修复已弃用 API 警告
• 升级前审查代码库中已移除或已弃用的 Neo4j API

不适用场景

• 编写新的 Cypher 查询 → neo4j-cypher-skill
• 数据库管理（备份、还原、导入、cypher-shell）→ neo4j-cli-tools-skill
• 从头开始 → neo4j-getting-started-skill
• GDS 算法迁移 — 此处不涵盖；请参阅 GDS 发布说明

---

入门条件

开始前，请询问：

1. 目标 Neo4j 版本 — 用于选择 Cypher 方言和驱动版本
2. 使用的语言 — 检查 package.json、requirements.txt、pom.xml、*.csproj、go.mod
3. 当前驱动版本 — 从依赖文件中读取；切勿猜测

如果目标版本 >= 2025.06：询问将使用 Cypher 5 还是 Cypher 25 方言（两者均受支持；Cypher 25 是新的默认方言）。

---

步骤 1 — 扫描代码库

# 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

修改前先收集发现结果。列出所有发现的已弃用模式。

---

步骤 2 — Cypher 迁移（4.x / 5.x → Cypher 25）

应用于每个 Cypher 字符串、.cypher 文件、OGM/SDN @Query 注解和模板字面量。

完整替换表

旧语法	Cypher 25 替代写法	说明
[:REL*1..5]	(()-[:REL]->()){1,5}	QPE 量词组
[:REL*]	(()-[:REL]->()){1,}	无界 QPE
[:REL*0..5]	(()-[:REL]->()){0,5}	允许零跳
shortestPath((a)-[*]->(b))	SHORTEST 1 (a)(()-[]->()){1,}(b)	QPE 最短路径
allShortestPaths((a)-[*]->(b))	ALL SHORTEST (a)(()-[]->()){1,}(b)	QPE 所有最短路径
id(n)	elementId(n)	返回字符串，而非整数
CALL { WITH x ... }	CALL (x) { ... }	显式导入语法
PERIODIC COMMIT	CALL (...) { ... } IN TRANSACTIONS OF 1000 ROWS	分批写入
-- comment	// comment	SQL 注释无效
SET n = r（结构值）	SET n = properties(r)	先提取映射
MERGE (a {x:1})-[:T]->(b {x:a.x})	重写 — 不允许跨实体 MERGE 引用	拆分为 MATCH+MERGE
CREATE INDEX ... OPTIONS { indexProvider: ... }	从 OPTIONS 中移除 indexProvider	已移除提供程序选择
db.create.setVectorProperty(...)	使用原生 VECTOR 属性类型	过程已移除
dbms.upgrade() / dbms.upgradeStatus()	使用 cypher-shell :sysinfo	过程已移除
USE composite.'1'	USE `composite.1`	对整个限定名称使用反引号
RETURN 1 as my$Identifier	RETURN 1 as `my$Identifier`	未转义标识符中已移除 $

向量索引查询（按版本区分）

版本	语法
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 方言前缀规则

• 目标版本 >= 2025.06，方言 = Cypher 25：在每个顶层查询前添加 CYPHER 25
• 目标版本 >= 2025.06，方言 = Cypher 5：添加 CYPHER 5（继续支持已弃用形式）
• 目标版本为 4.x 或 5.x：无需前缀；请从 references/cypher-queries.md 获取变更日志

id(n) → elementId(n) 注意事项

elementId() 返回字符串（例如 "4:abc123:0"），而非整数。请修复下游代码中将其存储为 int 或与 int 比较的部分。切勿将 elementId() 值用于数值运算。

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

---

步骤 3 — 驱动迁移

选择与步骤 1 中发现的语言对应的部分。

---

Python 驱动（5.x → 6.x）

最低要求：Python >= 3.10，neo4j 包（6.0+，于 2026 年 1 月 12 日发布）

包重命名 — 首先执行此操作

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

neo4j-driver 包自 6.0 起已弃用，不再接收更新。

已移除的 API

旧版	新版	说明
session.read_transaction(fn)	session.execute_read(fn)
session.write_transaction(fn)	session.execute_write(fn)
session.last_bookmark()	session.last_bookmarks()	返回 Bookmarks（复数形式）
Bookmark 类	Bookmarks 类
TRUST_ALL_CERTIFICATES	trusted_certificates=TrustAll()
TRUST_SYSTEM_CA_SIGNED_CERTIFICATES	trusted_certificates=TrustSystemCAs()
neo4j.conf、neo4j.data 模块	已移除 — 请使用顶层 neo4j.*

资源管理变更

驱动和会话不再在 GC 时自动关闭。请添加显式清理：

- 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:
+         ...

或者显式调用 .close()。重复调用 .close() 不会产生任何操作。

错误处理变更

旧版异常	新版异常	触发条件
ClientError（超时时）	ConnectionAcquisitionTimeoutError	获取超时
AuthError（配置无效时）	ConfigurationError	身份验证参数无效
为 Query 对象引发的 ValueError	TypeError	将 Query 传递给 Transaction.run

保持不变的关键 API

execute_query()、GraphDatabase.driver()、neo4j+s:// URI、auth=(user, pw)、会话 run()。

完整变更日志：references/python-driver.md

---

JavaScript / Node.js 驱动（5.x → 6.x）

最低要求：Node.js >= 18（请查看驱动 package.json 中的 engines）；软件包 neo4j-driver

已移除的 API

旧版	新版	说明
session.readTransaction(fn)	session.executeRead(fn)
session.writeTransaction(fn)	session.executeWrite(fn)
session.lastBookmark()	session.lastBookmarks()	返回数组
resultSummary.updateStatistics	resultSummary.counters
driver.verifyConnectivity() → ServerInfo	driver.getServerInfo() → ServerInfo	verifyConnectivity() 现在返回 void

在 6.0 中弃用（将在 7.0 中移除）

旧版	新版
isRetriableError(err)	isRetryable(err)
neo4jError.retriable	neo4jError.retryable
notificationCategory	notificationClassification

整数处理

Neo4j 整数映射为 neo4j.Integer（64 位）。进行算术运算时，请使用 .toNumber() 或 .toInt()。较大的值（> 2^53）会失去精度 — 请使用 .toString() 将其存储为字符串。

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

完整变更日志：references/javascript-driver.md

---

Java 驱动（5.x → 6.x）

最低要求：Java 21；Maven org.neo4j.driver:neo4j-java-driver:6.x

Maven 坐标

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

已移除的 API

已移除	替代方案	说明
RxSession / RxTransaction	使用异步 AsyncSession 或同步 Session	响应式 API 已移除
Bookmark 多值构造函数	Bookmark.from(iterable)
session.readTransaction(fn)	session.executeRead(fn)
session.writeTransaction(fn)	session.executeWrite(fn)
TrustStrategy.certFile()	TrustStrategy.trustCustomCertificateSignedBy(path)
Notification.severity()	Notification.severityLevel()	返回类型化枚举

依赖说明（BOM）

自 6.0.1 起，neo4j-java-driver-bom 不再导入 netty-bom。如果使用 Netty 原生传输，请显式导入 netty-bom。

日志记录

旧版 Logging API 已弃用 → 请改为配置 System.Logger。

完整变更日志：references/java-driver.md

---

.NET 驱动（5.x → 6.x）

最低要求：.NET 8、9 或 10（已停止支持 .NET Standard 2.1）；NuGet Neo4j.Driver 6.x

NuGet 软件包

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

Neo4j.Driver.Signed 不再接收更新 — 请切换到 Neo4j.Driver（现已签名）。

已移除的 API

已移除	替代方案	说明
ILogger	INeo4jLogger	接口已重命名
ConfigBuilder.WithIpv6Enabled()	删除调用 — 始终启用 IPv6
Config.Ipv6Enabled 属性	删除 — 始终为 true
Simple driver	使用标准的 IDriver	已完全移除

完整变更日志：references/dotnet-driver.md

---

Go Driver（5.x → 6.x）

最低要求：Go 1.24；模块 github.com/neo4j/neo4j-go-driver/v6

更新 go.mod

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

将所有导入路径中的 /v5/ 更新为 /v6/。

已移除的 API 和替代方案

旧版	新版	说明
neo4j.NewDriver(...)	neo4j.NewDriverWithContext(...)	支持上下文；也可以直接使用 neo4j.NewDriver（现在已支持上下文）
neo4j.Config 结构体	config.Config	导入 github.com/neo4j/neo4j-go-driver/v6/neo4j/config
neo4j.ServerAddressResolver	config.ServerAddressResolver
neo4j.LogLevel / neo4j.ERROR 等	log.Level / log.ERROR	导入 neo4j/log 子包
log.Console	log.ToConsole
log.Void	log.ToVoid
neo4j.Single[T]	neo4j.SingleT[T]（仍然存在；优先使用上下文变体）
neo4j.Driver 接口	neo4j.DriverWithContext	*WithContext 变体现为首选
neo4j.Session 接口	neo4j.SessionWithContext
Config.RootCAs 字段	Config.TlsConfig	直接传入 *tls.Config
通知常量（旧包）	对应的 notifications.*	导入 neo4j/notifications

上下文 API 整合

在 v6 中，neo4j.NewDriverWithContext 是规范的构造函数。旧的 *WithContext 方法名已弃用（计划在 v7 中移除）——基础名称现在默认包含上下文。

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

完整迁移指南：references/go-driver.md

---

第 4 步 — 版本兼容性矩阵

Neo4j 版本	Cypher 方言	兼容 Driver 6.x	说明
4.4 LTS	Cypher 4	是（bolt 兼容）	支持已于 2025 年 11 月结束
5.26 LTS	Cypher 5	是	支持至 2028 年 11 月
2025.01–2025.05	Cypher 5	是	CalVer 时代开始
2025.06+	Cypher 5 或 25	是	Cypher 25 成为新默认版本
2026.01+	Cypher 25	是	可使用 SEARCH 子句
2026.07.0	Cypher 25	是	跳过此补丁版本 — 块格式中的 UTF-8 回归问题会导致 trim() 查询失败并损坏存储的字符串；升级目标为 2026.07.1
2026.08+	Cypher 25	是	新增 UUID 类型和字符串插值；UUID 属性要求 Driver >= 6.2（Python >= 6.3）——较旧的 Driver 会返回占位符 MAP 并发出警告 03N95；2026.08 随附 Java Driver 6.2.1；跳过 2026.08.0（查询失败问题）——目标版本为 2026.08.1+
2026.09+	Cypher 25	是	SEARCH 子句支持 FULLTEXT INDEX；页面缓存会在启动时预留全部 server.memory.pagecache.size
2026.12 LTS 之后的 Aura	Cypher 25	是	dbms.components() 从固定的 5.27 切换为日历版本（例如 2027.01）——修复解析 5.x 字符串的代码（包括 Kafka/Spark/GraphQL 集成）
Aura 2027.01	Cypher 25	是	创建或更改原生用户密码时，最低长度从 8 个字符提高到 16 个字符

存储格式：4.4 到 2026.x 之间没有变化。自 5.22 起，新建的 Enterprise 数据库默认使用 block 格式。high_limit 和 standard 在 5.23 中弃用，并将在 2026 LTS 之后移除——该 LTS 之后，Neo4j 将拒绝在 high_limit 存储上启动；请在该 LTS 当天或之前离线运行 neo4j-admin database migrate --to-format=block <db>。

服务器 JVM：2026.x 在 Java SE 21 或 25 上运行；Java 21 支持将在 2026 LTS 结束——将服务器迁移到 Java 25 [2026.08 弃用项]。

不支持降级 — 在升级任何服务器之前，请先备份。

---

第 5 步 — 迁移后测试

# 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 ./...

测试运行后：如果出现任何 DeprecationWarning 或弃用 API 日志，请将其视为错误 — 继续之前先修复。

对于 Cypher：先通过 EXPLAIN 运行每个已迁移的查询：

# 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>"}'

---

常见迁移错误

错误	原因	修复方法
id(n) 返回字符串，整数比较失败	elementId() 返回字符串	将已存储的 ID 更新为字符串；修正 WHERE 子句
Cannot merge node using null property value	MERGE 键解析为 null	在执行 MERGE 前验证参数
Neo4j.Driver.Exceptions.AuthenticationException	.NET 重命名后凭据配置错误	更新 INeo4jLogger 的用法；检查配置
TypeError: neo4j-driver is deprecated	安装了旧版软件包	在 requirements 中将 neo4j-driver 替换为 neo4j>=6.0.0
AttributeError: 'Session' has no 'read_transaction'	Python 5→6，方法已移除	替换为 execute_read()
RxSession not found	Java 6.x，Reactive API 已移除	迁移到异步或同步会话
undefined is not a function (.readTransaction)	JS 6.x，方法已移除	替换为 executeRead()
Go：undefined: neo4j.Config	仍在使用 v5 导入路径	将所有导入更新为 /v6/
PERIODIC COMMIT not supported	Cypher 25 中已移除该子句	使用 CALL (...) IN TRANSACTIONS
Unknown function id()	Cypher 25 中已移除 id()	替换为 elementId()

---

参考资料

按需加载——由于有明确链接，发现率较高：

• references/cypher-queries.md — 按版本选择 Cypher 更新日志（4.x、5.x、2025.x）
• references/python-driver.md — Python 更新日志 URL 和完整版本历史
• references/javascript-driver.md — 按版本分类的 JS 更新日志 URL
• references/java-driver.md — 按版本分类的 Java 更新日志 URL
• references/dotnet-driver.md — 按版本分类的 .NET 更新日志 URL
• references/go-driver.md — 包含 5.0 和 6.0 章节的 Go 迁移指南

对于上述内容未涵盖的语法，请获取： https://neo4j.com/docs/cypher-manual/25/deprecations-additions-removals-compatibility/

---

检查清单

• 已确认目标 Neo4j 版本；已选择 Cypher 方言（Cypher 5 或 25）
• 已扫描依赖文件；已识别所有驱动程序版本
• 已将 Cypher 替换表应用到代码库中的每个查询
• 已将 id(n) → elementId(n)，并修复后续的 int→string 转换
• 已在所有批量写入中将 PERIODIC COMMIT → CALL IN TRANSACTIONS
• 已在所有子查询中将 CALL { WITH x ... } → CALL (x) { ... }
• 已完成软件包重命名（Python：neo4j-driver → neo4j）
• 已替换弃用的会话方法（read_transaction/readTransaction → execute_read/executeRead）
• 已补充缺失的资源清理操作（Python：上下文管理器或 .close()）
• 已更新书签 API（last_bookmark → last_bookmarks，Bookmark → Bookmarks）
• 已将 Go 导入从 /v5/ 更新为 /v6/；neo4j.Config → config.Config
• Java：已确认使用 Java 21；已移除 RxSession 用法
• .NET：ILogger → INeo4jLogger；Neo4j.Driver.Signed → Neo4j.Driver
• 测试通过，且没有 DeprecationWarnings
• 已对所有迁移后的 Cypher 查询运行 EXPLAIN；没有错误