neo4j-migration-skill

使用する場面

• ドライバーの依存関係を 4.x または 5.x から 6.x にアップグレードする場合
• Cypher クエリを Cypher 25 の構文に移行する場合
• ドライバーまたは Neo4j のバージョンアップ後に非推奨 API の警告を解消する場合
• アップグレード前に、削除済みまたは非推奨の Neo4j API がないかコードベースを監査する場合

使用しない場面

• 新しい Cypher クエリを記述する場合 → neo4j-cypher-skill
• DB 管理（バックアップ、復元、インポート、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}	0 ホップを許可
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 (structural val)	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 として保存または比較している場合は修正してください。数値演算に 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）

neo4j-java-driver-bom は、6.0.1 以降 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 property	削除 — 常に true
Simple driver	標準の IDriver を使用	完全に削除

変更履歴全文：references/dotnet-driver.md

---

Go ドライバー（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 struct	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 interface	neo4j.DriverWithContext	*WithContext バリアントが主要なものになりました
neo4j.Session interface	neo4j.SessionWithContext
Config.RootCAs field	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 プロパティにはドライバー >= 6.2（Python >= 6.3）が必要です — それより古いドライバーはプレースホルダー MAP を返し、03N95 の警告を出します。2026.08 には Java ドライバー 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 まで変更はありません。新規 Enterprise データベースでは、5.22 以降 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 に関するログが表示された場合は、ERROR として扱い、先に進む前に修正してください。

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 でリアクティブ 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 を実行し、エラーがない