Skip to content

docs: explain legacy GraphID upgrade preflight #523

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
imbajin wants to merge 3 commits into
base: master
Choose a base branch
from
Open

docs: explain legacy GraphID upgrade preflight #523

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
1f0edeb
docs: explain legacy graphid preflight
imbajin Oct 12, 2026
6596f60
docs: link the current graphid upgrade guide
imbajin Oct 12, 2026
0f29645
docs: clarify store preflight availability
imbajin Oct 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions content/cn/docs/config/config-backend-hstore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -208,3 +208,19 @@ curl http://localhost:8080/metrics/backend
```

响应中的 `nodes` 就是 PD 返回的活跃 Store 数量。`nodes` 为 `0` 说明 Server 连上了 PD，但 PD 中没有状态为 `Up` 的 Store，通常是 Store 节点还没注册，或者因为不在 PD 的 `pd.initial-store-list` 中而注册成了 `Pending`。

### 9 旧 GraphID 升级预检

以下检查仅适用于包含 [Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330) 所提实现的 Store 构建。
该修复尚未合入 Apache HugeGraph，也未包含在 Apache 发行版中。更早的 1.8 构建不保证具备该保护；依赖下述拒绝行为前，先确认所用构建包含该修复。

这些 Store 构建会在分配缺失的图 ID、元数据启动阶段首次打开尚未缓存的分区 DB、启动该分区的 Raft 状态机，或激活暂存快照前检查已有图数据列族。
首次打开时会在清理旧版本前检查所有仍保留的有效 DB 版本。发现保留前缀 `FFFE` 的旧数据时会拒绝操作；
如果选中的不完整 DB 版本缺少 `CURRENT`、会遮蔽仍保留的有效版本，也会拒绝。
这针对受影响的旧写入路径，不表示所有 1.7 数据库都需要迁移，持久化 ID 格式保持不变。

遇到拒绝时，保留原始数据 DB 版本、元数据、WAL，以及输入快照和暂存副本，在恢复写入或回放前调查相关写入与升级历史。
不要删除图到 ID 的映射，也不要把所有保留前缀行归给同一个图，因为不同图可能共享该前缀。Store/Raft 位置元数据可能已在预检前更新，因此整个启动流程并非只读。
预检不会自动迁移数据或修复归属；完整的 1.7 升级与恢复仍需针对具体部署验证。

详细行为与处置依据见[所提源码版本的升级指南](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)。
22 changes: 22 additions & 0 deletions content/en/docs/config/config-backend-hstore.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -246,3 +246,25 @@ curl http://localhost:8080/metrics/backend
The `nodes` value in the response is the count of active stores PD returns. A `nodes` value of `0` means the
Server reached PD but PD has no store in state `Up`, which usually means the Store nodes have not registered
yet, or registered as `Pending` because they are not in PD's `pd.initial-store-list`.

### 9 Legacy GraphID upgrade preflight

The following checks apply only to Store builds containing the implementation proposed in
[Apache HugeGraph #3330](https://github.com/apache/hugegraph/pull/3330).
This change is not yet merged into Apache HugeGraph or included in an Apache release. Earlier 1.8 builds do not guarantee this guard; verify that your

@bitflicker64 bitflicker64 Oct 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: "Earlier 1.8 builds do not guarantee this guard" is weaker than the code and leaves out the release people actually run (same wording on line 215 of the Chinese page: "更早的 1.8 构建不保证具备该保护").

Evidence: git grep -c "checkLegacyGraphIdData\|resolveExistingDBPath" origin/master -- hugegraph-store on apache/hugegraph master (0b7c0de3e) returns nothing, and the 1.7.0 tag has neither method. 1.7.0 is also where the sentinel comes from (GraphIdManager.maxGraphID = 65535 - 1, which is 0xFFFE). So the check is absent from 1.7.0 and from every master build so far, not merely unguaranteed, and a 1.7.0 operator reading "earlier 1.8 builds" is not told that their Store never refuses.

Requested change: state it as a fact in both pages, for example "No Apache release, including 1.7.0, and no master build before #3330 contains this check". This sentence and "not yet merged" also need an update in the same change that merges #3330, so please note that on the code PR.

build contains the fix before relying on the refusal behavior below.

These Store builds check existing graph-data column families before allocating a missing graph ID, first opening a cold
partition DB during metadata bootstrap, starting its Raft state machine, or activating a staged snapshot. Before pruning, the first cold DB open checks
all retained valid versions. Reserved `FFFE` legacy rows cause refusal.
An incomplete selected DB version without `CURRENT` is also rejected when it would hide retained valid versions. This concerns affected old write paths;
it does not mean that every 1.7 database needs migration, and the persisted ID format is unchanged.

On refusal, preserve the original data DB versions, metadata, WAL and incoming/staged snapshots. Investigate the affected write and upgrade history before
resuming writes or replay. Do not delete graph-to-ID mappings or assign all reserved-prefix rows to one graph: different graphs may share that prefix.
Store/Raft location metadata may already have been updated before the check, so the entire bootstrap is not read-only. The check performs no automatic
migration or ownership repair; a complete 1.7 upgrade and recovery still require deployment-specific validation.

See the
[guide for the proposed revision](https://github.com/hugegraph/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md)

@bitflicker64 bitflicker64 Oct 13, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Minor: this guide link (and the one on line 226 of content/cn/docs/config/config-backend-hstore.md) points at the hugegraph/hugegraph fork, while the sentence above it cites Apache HugeGraph #3330 as the source.

Evidence: 27731930 is the current head of apache/hugegraph#3330, and the same file resolves in the Apache repository: gh api -X GET "repos/apache/hugegraph/contents/docs/store-graphid-upgrade.md?ref=27731930ce4573481ac2f01092a288b0db239b53" returns https://github.com/apache/hugegraph/blob/27731930ce4573481ac2f01092a288b0db239b53/docs/store-graphid-upgrade.md. A page on hugegraph.apache.org then sends readers to a non-Apache organisation for the upgrade guidance, and the two references in one section name two different repositories for one change.

Requested change: use the apache/hugegraph URL for the pinned revision in both pages, and switch it to the master path once #3330 is merged.

for details.
Loading