Repository navigation
docs(clients): document transaction abort reason categories - #783
Draft
matthewmcneely wants to merge 4 commits into
Draft
matthewmcneely wants to merge 4 commits into
matthewmcneely wants to merge 4 commits into
Conversation
…ehaviour
Three things had gone stale or were wrong.
UNKNOWN was documented as meaning "an older server", in four places. A current
server also returns uncategorized aborts, on purpose: where no published
category fits the cause it sends the explanation without a code rather than
borrowing one that implies the wrong remedy. A reader hitting UNKNOWN would
otherwise conclude their server was out of date. The three categories are also
no longer presented as exhaustive.
raw-http.md quoted a message the server cannot produce ("stale-startts:
Transaction has been aborted due to a leader change. Please retry") and told
readers the category is a prefix on the message. It is not: the HTTP layer
renders the underlying gRPC error, so an "rpc error: code = Aborted desc = "
preamble precedes it. Anchoring a match to the start of the string fails. The
JSON example now shows the real shape, and the guidance is to match the code
within the message - better still, to treat the error response itself as the
abort signal and use the category only to decide how to react, since message
text is not a stable contract.
stale-startts described one of its two causes. Zero raises its validation floor
on a leader change and also when trimming its conflict map at a snapshot, which
is not a leader change.
Adds what a conflict can and cannot tell you: it names no predicate or uid and
cannot, but the collision may be on an index or count key derived from the data
written, and @upsert excludes the uid so any two transactions writing the same
value collide. Reverse edges never conflict.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Adds a "Handling aborted transactions" section for dgo's AbortedError (dgraph-io/dgo#288), lists Go alongside Java and Python, and updates the examples for the server's final message format, where every abort carries "Transaction has been aborted. Please retry" after the category. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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
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.
Description
This PR documents the transaction abort reason categories from dgraph-io/dgraph#9747 across the client pages. It supersedes #761, which the stale bot closed. I couldn't push to that branch, so this one carries @rahst12's two commits as is, merged with current
main, plus a commit on top.From #761:
clients/index.md: new "Abort reasons" subsection covering the three categories (conflict,stale-startts,predicate-move), uncategorized aborts, and what a conflict can't tell you.clients/java.mdandclients/python.md: handling aborts withTxnConflictException.getReason()andAbortedError.reason.clients/raw-http.md: updated abort response example and a table of codes.Added here:
clients/go.md: a "Handling aborted transactions" section for*dgo.AbortedError(feat(txn): surface transaction abort reason on AbortedError dgo#288), including theerrors.Isvs==note.<code>: Transaction has been aborted. Please retry. <detail>. Every abort still contains the legacy sentence.Related PRs
Hold merge until the server and client releases ship.
Need help on this PR? Tag
@codesmith-botwith what you need.