docs: document DatabaseError and its fields - #3788
Open
u9822914324-web wants to merge 1 commit into
Open
u9822914324-web wants to merge 1 commit into
u9822914324-web wants to merge 1 commit into
Conversation
Closes brianc#3770. The only guidance on error handling was a short try/catch example on the landing page, which left no way to find out what a server error actually carries. This adds a pg.DatabaseError API page covering every field, and links it from that section. Field descriptions and their protocol letters are taken from parseErrorMessage in packages/pg-protocol/src/parser.ts, so they match what the driver actually populates rather than the PostgreSQL docs alone. The page also spells out two things that are easy to get wrong: every field except message, length, and name is optional and can be undefined, and name is 'error' rather than 'DatabaseError' because it shadows Error.name. Co-Authored-By: Claude Opus 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
1 participant
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.
Closes #3770.
Why
The only error-handling guidance in the docs is a short
try/catchexample on the landing page. It shows that errors happen but not what they contain, so there is no documented way to find out that a failure carries a SQLSTATEcode, aconstraint, or adetail— which is exactly what you need to handle an expected error like a unique violation.What
docs/pages/apis/errors.mdx(pg.DatabaseError) documenting every field, with an example that branches onerr instanceof DatabaseErrorto separate server-side failures from connection/TLS/timeout failures.docs/pages/apis/_meta.jsnext topg.Result.Accuracy
Field descriptions and their protocol letters were taken from
parseErrorMessageinpackages/pg-protocol/src/parser.ts, so they describe what the driver actually populates rather than being transcribed from the PostgreSQL manual. The page calls out two things that are easy to get wrong:message,length, andnameis optional and can beundefined, since the server only sends the fields that applynameis'error', not'DatabaseError'— it shadows the usualError.nameDocs-only; no runtime code touched.
prettier --checkpasses on all three files.yarn lintscopes topackages/**andbenchmark/**, so it is unaffected.This was prepared with AI assistance (Claude); the source mapping and field semantics were verified against the parser in this repository.
🤖 Generated with Claude Code