refactor(graph): clarify thread id naming in checkpoint savers - #107
Merged
yuluo-yx merged 1 commit intoSep 30, 2026
Merged
Conversation
The persistence savers accept a user-facing thread id through RunnableConfig but store it in a thread_name column, while the thread_id column holds an internal surrogate UUID generated to support thread release and reuse. This split was introduced by the saver rework in spring-ai-alibaba#3287 and kept the old column names, so thread_id now names the internal key instead of the user-facing id, which makes the storage layer easy to misread. Make the identity model explicit without touching stored data or SQL: document the two identities in every saver and in AbstractJdbcCheckpointSaver, annotate the schema comments with what each column actually holds, and rename internal Java identifiers so threadId always means the user-facing id and persistedThreadId always means the internal surrogate UUID.
yuluo-yx
approved these changes
Sep 30, 2026
yuluo-yx
left a comment
yuluo-yx
left a comment
Contributor
There was a problem hiding this comment.
LGTM, everything is good
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Describe what this PR does / why we need it
thread_idandthread_namein the checkpoint savers' storage are easy to misread: the thread id accepted by the API (RunnableConfig.threadId) ends up in thethread_namecolumn, while thethread_idcolumn holds an internally generated UUID. As raised in #106, this split came in with the saver rework (spring-ai-alibaba#3287) to support "release and later reuse the same thread id", but the old column names were kept, sothread_idnow names the internal surrogate key instead of the user-facing thread id.This PR makes the identity model explicit without changing any SQL statement, stored key or persisted data, because renaming the columns would silently break existing deployments:
AbstractJdbcCheckpointSaver: document the thread identity model, and replace the vaguethread name/id used by the concrete saver schemaparameter docs with a precise statement of what the protected methods receive.threadName->threadIdfor the user-facing id).threadName(RunnableConfig)tothreadId(RunnableConfig), and usepersistedThreadIdfor the internal UUID so the two identities no longer share a name inside one method.Does this pull request fix one issue?
Fixes #106
Describe how you did it
Confirmed the schema history first (before spring-ai-alibaba#3287 the single-table savers keyed on the user's thread id directly, matching the LangGraph model), then applied a naming/documentation-only cleanup on top of the current two-identity design:
threadIdalways denotes the user-facing thread id fromRunnableConfig,persistedThreadIdalways denotes the internal surrogate UUID, and every saver's schema documentation now spells out which column/field holds which.Describe how to verify it
mvn -pl agentic-ai-graph-core test— the full module suite passes (439 tests, 0 failures, 15 skipped), including the container-backed saver tests for H2, MySQL, PostgreSQL, Oracle, Redis and MongoDB.Special notes for reviews
The physical column rename suggested in the issue would orphan data written by existing deployments, so it is intentionally left to the successor persistence artifacts (agentic-spring-ai-extensions); this PR removes the confusion at the Java and documentation level where it can be done compatibly.