Skip to content

fix: reuse connections after result errors and fix oneFirst, routed retry limit, 22P02 cause and docs - #829

Merged
gajus merged 3 commits into
mainfrom
gajus/bug-cleanup
Nov 5, 2026
Merged

gajus merged 3 commits into
mainfrom
gajus/bug-cleanup

Conversation

@gajus

@gajus gajus commented Nov 5, 2026 •

Copy link
Copy Markdown
Owner

Fixes a set of inconsistencies between the API, its implementation and the documentation.

Reuse connections after result errors

A query that failed with NotFoundError, DataIntegrityError or SchemaValidationError destroyed its connection, e.g. every pool.one() that found no rows. These errors describe the result of a query that succeeded, so the connection is healthy: it is now returned to the pool. This applies to queries and transactions on the pool. A routine passed to pool.connect() can leave the connection in any state, so its connection is still destroyed when the routine fails.

oneFirst throws DataIntegrityError for multiple columns

oneFirst threw UnexpectedStateError when the query returned multiple columns (it passed its column check to one(), which ignored it). It now throws DataIntegrityError ("Query returned rows with multiple columns."), as documented, and like maybeOneFirst, anyFirst and manyFirst. The error also goes through the dataIntegrityError interceptor now.

Remove the values parameter from the query method types

The query methods accepted a second values parameter, which was ignored. It is removed from the types. TypeScript code that passed it no longer compiles; this is marked as minor, because the values were never used.

retryLimit option of transaction()

transaction() accepts options instead of a number, e.g. pool.transaction(handler, { retryLimit: 3 }). Passing the retry limit as the second argument (pool.transaction(handler, 3)) still works, but is deprecated. The new TransactionOptions type is exported.

pool.transaction() used to drop the retry limit when a beforePoolConnection interceptor returned another pool; the options are now passed to that pool.

Errors of row transformers in stream()

When a transformRow or transformRowAsync interceptor threw during stream() (e.g. a result parser that throws SchemaValidationError), the error became an unhandled rejection (which crashes the process by default), stream() never settled, and the connection was never released. Now:

  • stream() rejects with the error.
  • stream() waits for the promise returned by the stream handler, e.g. an async function that uses for await, which rejects when the stream fails.
  • When the consumer of a stream fails, the driver destroys the query stream, which closes the cursor. Previously the cursor stayed open (pipe does not propagate destruction), and every subsequent query of the connection waited behind it, e.g. the ROLLBACK of the surrounding transaction.

Keep the original error of 22P02

InvalidInputError raised for SQLSTATE 22P02 (invalid text representation) now includes the original error as cause, like the other errors that the driver maps.

Documentation

  • There is no runtime check of how a query was constructed (a manually constructed query object runs). The documentation now describes the actual protection: the query method types, and the sql tag functions throwing InvalidInputError when they are not called as tagged template literals.
  • The nested transaction example called t1.transaction inside of t2, which throws "Cannot run a query using parent transaction."; it now calls t2.transaction.
  • The pool error event is emitted when a query fails with a SlonikError, not for all errors.
  • afterQueryExecution, beforeQueryExecution and beforeQueryResult are not executed for queries executed using stream.
  • All notes use > [!NOTE] blocks.

Tests

  • Connections are re-used after NotFoundError, DataIntegrityError and SchemaValidationError (implicit queries and transactions), and not re-used after a failed pool.connect() routine.
  • oneFirst throws DataIntegrityError for multiple columns.
  • The retryLimit option limits the retries of transactions and nested transactions; so does the deprecated retry limit argument.
  • A routed transaction receives the options.
  • The 22P02 InvalidInputError has the original error as cause.
  • stream() rejects with the error of a transformRow / transformRowAsync interceptor (using a data listener and for await), after which the connection is re-used; a transaction in which a stream failed is rolled back; a connection can run queries after a stream failed.

@changeset-bot

changeset-bot Bot commented Nov 5, 2026 •

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 622ae06

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 14 packages
Name Type
@slonik/pg-driver Minor
slonik Minor
@slonik/benchmark Minor
@slonik/driver Minor
@slonik/errors Minor
@slonik/dataloaders Minor
slonik-interceptor-field-name-transformation Minor
slonik-interceptor-query-cache Minor
slonik-interceptor-query-logging Minor
slonik-sql-tag-raw Minor
@slonik/sql-tag Minor
@slonik/test-ssls Minor
@slonik/types Minor
@slonik/utilities Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Comment thread README.md Outdated

This function can optionally return a direct result of the query which will cause the actual query never to be executed.

Note: Not executed for queries executed using `stream`.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

use special blockquotes for all notes, e.g.

Note

Useful information that users should know, even when skimming content.

Update all similar notes in README to use the same format instead of plain note:

"slonik": minor
---

fix: `pool.transaction(handler, transactionRetryLimit)` passes `transactionRetryLimit` to the pool returned by a `beforePoolConnection` interceptor.

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

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

Avoid literal configuration values. Pass instead {retryLimit?: number} object.

@gajus
gajus merged commit bed6b20 into main Nov 5, 2026
4 checks passed
@github-actions github-actions Bot mentioned this pull request Nov 5, 2026

This branch was previously deployed

1 inactive deployment
release — 622ae061 Deployed Nov 5, 2026 by gajus via Test node_version:24 test_only:utilities #450
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant