Repository navigation
Conversation
Errors from the server carry the SQLSTATE in `code`, but errors that the client creates itself (connection and query timeouts, a terminated connection, SSL refusal) had none, so callers had to match messages. Give the runtime ones an `ERR_PG_` code and document them. Messages stay the same. Errors for library misuse are left without a code. Closes brianc#3380
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.
PostgreSQL server errors expose a SQLSTATE through
err.code, but errors created by the client—such as timeouts, connection termination, and SSL negotiation failures—lack codes. Consumers therefore have to match error messages to handle these cases (#3380).This PR adds
ERR_PG_codes to these runtime errors without changing their messages or error types.ERR_PG_CONNECTION_TIMEOUTtimeout expiredERR_PG_CONNECTION_TERMINATEDConnection terminated unexpectedlyERR_PG_CONNECTION_ENDEDConnection terminatedERR_PG_QUERY_TIMEOUTQuery read timeoutERR_PG_SSL_NOT_SUPPORTEDThe server does not support SSL connectionsERR_PG_SSL_NEGOTIATION_FAILEDThere was an error establishing an SSL connectionERR_PG_POOL_CONNECT_TIMEOUTConnection terminated due to connection timeoutERR_PG_POOL_CHECKOUT_TIMEOUTtimeout exceeded when trying to connectThe naming follows the Node-style
ERR_PG_…convention discussed in #2498 and does not overlap with server SQLSTATEs. Following the same review guidance, API misuse errors, such as using an ended pool or callingend()twice, remain unchanged.In the native client, only query timeouts and the
Connection terminatederror fromend()receive these codes. Connection and SSL errors come from libpq and remain without a code. The client and pool documentation now include error-code tables.Compatibility
Although messages and error types remain unchanged, consumers that identify server errors using
typeof err.code === 'string'may behave differently.For example, Prisma's adapter-pg checks an allowlist of TLS codes when
codeis a string. With this change, the two SSL errors above are no longer classified asP1011, as verified with Prisma 7.8.0. If this PR is merged, I plan to submit a follow-up PR to Prisma adding both codes to that list.An existing pg-pool test also assumed that any error with a code must be
ECONNRESET; this PR updates that assertion.Testing
yarn testsuite passes on Linux with Node.js 24 and PostgreSQL 17, including tests using the native bindings.Closes #3380.