From cbbdcc3de2a3a0c2f42db33f9925079af56c8d4c Mon Sep 17 00:00:00 2001 From: Gajus Date: Thu, 5 Nov 2026 14:49:27 -0800 Subject: [PATCH 1/3] fix: reuse connections after result errors and fix oneFirst, routed retry limit, 22P02 cause and docs --- .changeset/invalid-input-error-cause.md | 5 + .changeset/one-first-data-integrity-error.md | 5 + .../remove-query-method-values-parameter.md | 5 + .../reuse-connection-after-result-errors.md | 5 + .changeset/routed-transaction-retry-limit.md | 5 + README.md | 25 ++--- .../src/factories/createPgDriverFactory.ts | 2 +- .../interceptors/beforePoolConnection.test.ts | 26 +++++ packages/slonik/src/binders/bindPool.ts | 2 +- .../src/connectionMethods/oneFirst.test.ts | 5 +- .../slonik/src/connectionMethods/oneFirst.ts | 26 +---- .../slonik/src/factories/createConnection.ts | 41 ++++--- .../helpers.test/createIntegrationTests.ts | 1 + .../src/helpers.test/createPoolTests.ts | 104 +++++++++++++++++- packages/slonik/src/types.ts | 15 +-- 15 files changed, 201 insertions(+), 71 deletions(-) create mode 100644 .changeset/invalid-input-error-cause.md create mode 100644 .changeset/one-first-data-integrity-error.md create mode 100644 .changeset/remove-query-method-values-parameter.md create mode 100644 .changeset/reuse-connection-after-result-errors.md create mode 100644 .changeset/routed-transaction-retry-limit.md diff --git a/.changeset/invalid-input-error-cause.md b/.changeset/invalid-input-error-cause.md new file mode 100644 index 00000000..2fd5de67 --- /dev/null +++ b/.changeset/invalid-input-error-cause.md @@ -0,0 +1,5 @@ +--- +"@slonik/pg-driver": minor +--- + +fix: `InvalidInputError` raised for SQLSTATE 22P02 (invalid text representation) includes the original error as `cause`, like the other errors that the driver maps. diff --git a/.changeset/one-first-data-integrity-error.md b/.changeset/one-first-data-integrity-error.md new file mode 100644 index 00000000..9d855668 --- /dev/null +++ b/.changeset/one-first-data-integrity-error.md @@ -0,0 +1,5 @@ +--- +"slonik": minor +--- + +fix: `oneFirst` throws `DataIntegrityError` (instead of `UnexpectedStateError`) when the query returns multiple columns, like `maybeOneFirst`, `anyFirst` and `manyFirst`. diff --git a/.changeset/remove-query-method-values-parameter.md b/.changeset/remove-query-method-values-parameter.md new file mode 100644 index 00000000..9f7cf721 --- /dev/null +++ b/.changeset/remove-query-method-values-parameter.md @@ -0,0 +1,5 @@ +--- +"slonik": minor +--- + +remove the `values` parameter from the types of the query methods (e.g. `pool.query(query, values)`). The parameter was accepted, but ignored; values are bound using the `sql` tag. diff --git a/.changeset/reuse-connection-after-result-errors.md b/.changeset/reuse-connection-after-result-errors.md new file mode 100644 index 00000000..560720b8 --- /dev/null +++ b/.changeset/reuse-connection-after-result-errors.md @@ -0,0 +1,5 @@ +--- +"slonik": minor +--- + +fix: a query that fails with `NotFoundError`, `DataIntegrityError` or `SchemaValidationError` (e.g. `pool.one()` that finds no rows) no longer destroys its connection; the connection is returned to the pool. This applies to queries and transactions on the pool. Connections used by `pool.connect()` are still destroyed when the routine fails. diff --git a/.changeset/routed-transaction-retry-limit.md b/.changeset/routed-transaction-retry-limit.md new file mode 100644 index 00000000..aa639f7b --- /dev/null +++ b/.changeset/routed-transaction-retry-limit.md @@ -0,0 +1,5 @@ +--- +"slonik": minor +--- + +fix: `pool.transaction(handler, transactionRetryLimit)` passes `transactionRetryLimit` to the pool returned by a `beforePoolConnection` interceptor. diff --git a/README.md b/README.md index 45ea75f7..9660a55e 100644 --- a/README.md +++ b/README.md @@ -389,9 +389,7 @@ To begin with, Slonik does not allow running plain-text queries. connection.query("SELECT 1"); ``` -The above invocation would produce an error: - -> TypeError: Query must be constructed using `sql` tagged template literal. +Query methods only accept queries constructed using the `sql` tagged template literal, so TypeScript rejects the above invocation. This means that the only way to run a query is by constructing it using [`sql` tagged template literal](https://github.com/gajus/slonik#value-placeholders-tagged-template-literals), e.g. @@ -808,7 +806,7 @@ Read: [Protecting against unsafe connection handling](#protecting-against-unsafe The `DatabasePool` extends `DatabasePoolEventEmitter` and exposes the following events: -- `error`: `(error: SlonikError) => void` – emitted for all errors that happen within the pool. +- `error`: `(error: SlonikError) => void` – emitted when a query (including `stream`) fails with a `SlonikError`. Database errors that Slonik does not map to its own [error classes](#error-handling) are not emitted. ```ts import { createPool, type DatabasePoolEventEmitter } from "slonik"; @@ -1069,18 +1067,22 @@ pool.connect(); Executed after query has been executed and before rows were transformed using `transformRow`. -Note: When query is executed using `stream`, then `afterQuery` is called with empty result set. +Note: Not executed for queries executed using `stream`. #### beforeQueryExecution 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`. + #### beforeQueryResult Executed just before the result is returned to the client. Use this method to capture the result that will be returned to the client. +Note: Not executed for queries executed using `stream`. + #### beforeTransformQuery Executed before `transformQuery`. Use this interceptor to capture the original query (e.g. for logging purposes). @@ -1573,25 +1575,18 @@ query with 'baz' value binding. ### Manually constructing the query -Manually constructing queries is not allowed. - -There is an internal mechanism that checks to see if query was created using `sql` tagged template literal, i.e. +Query methods only accept queries constructed using the `sql` tagged template literal, so TypeScript rejects a manually constructed query, e.g. ```ts const query = { sql: "SELECT 1 AS id FROM foo WHERE bar = $1", - type: "SQL", values: ["baz"], }; connection.query(query); ``` -Will result in an error: - -> Query must be constructed using `sql` tagged template literal. - -This is a security measure designed to prevent unsafe query execution. +The `sql` tag functions must be called as tagged template literals. Calling one as a regular function, e.g. `sql.unsafe("SELECT 1")`, throws `InvalidInputError` ("Function must be called as a template literal."). This prevents passing a plain string (e.g. user input) as the query text. Furthermore, a query object constructed using `sql` tagged template literal is [frozen](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/freeze) to prevent further manipulation. @@ -2853,7 +2848,7 @@ await connection.transaction(async (t1) => { await t1.transaction(async (t2) => { await t2.query(sql.typeAlias("void")`INSERT INTO qux (quux) VALUES ('corge')`); - await t1.transaction(async (t3) => { + await t2.transaction(async (t3) => { await t3.query(sql.typeAlias("void")`INSERT INTO uier (grault) VALUES ('garply')`); return Promise.reject(new Error("foo")); diff --git a/packages/pg-driver/src/factories/createPgDriverFactory.ts b/packages/pg-driver/src/factories/createPgDriverFactory.ts index eea7e415..3dc13660 100644 --- a/packages/pg-driver/src/factories/createPgDriverFactory.ts +++ b/packages/pg-driver/src/factories/createPgDriverFactory.ts @@ -211,7 +211,7 @@ const wrapError = (error: Error, query: null | Query) => { } if (error.code === "22P02") { - return new InvalidInputError(error.message); + return new InvalidInputError(error.message, { cause: error }); } if (error.code === "25P03") { diff --git a/packages/slonik/src/binders/bindPool.test/interceptors/beforePoolConnection.test.ts b/packages/slonik/src/binders/bindPool.test/interceptors/beforePoolConnection.test.ts index 5f52ca6d..e7610b55 100644 --- a/packages/slonik/src/binders/bindPool.test/interceptors/beforePoolConnection.test.ts +++ b/packages/slonik/src/binders/bindPool.test/interceptors/beforePoolConnection.test.ts @@ -1,5 +1,6 @@ import { createPoolWithSpy } from "../../../helpers.test/createPoolWithSpy.js"; import { createTestRunner } from "../../../helpers.test/createTestRunner.js"; +import type { DatabasePool } from "../../../types.js"; import { createPgDriverFactory } from "@slonik/pg-driver"; import { createSqlTag } from "@slonik/sql-tag"; import * as sinon from "sinon"; @@ -29,6 +30,31 @@ test("`beforePoolConnection` is called before `connect`", async (t) => { t.true(beforePoolConnection.calledBefore(spy.acquire)); }); +test("`beforePoolConnection` that returns a pool runs the transaction using that pool, with the same retry limit", async (t) => { + const transaction = sinon.stub().resolves("foo"); + + const { pool } = await createPoolWithSpy(t.context.dsn, { + driverFactory, + interceptors: [ + { + beforePoolConnection: () => { + return { + transaction, + } as unknown as DatabasePool; + }, + name: "foo", + }, + ], + }); + + const handler = async () => { + return "bar"; + }; + + t.is(await pool.transaction(handler, 3), "foo"); + t.deepEqual(transaction.firstCall.args, [handler, 3]); +}); + test("pool connection lifecycle reuses the same context object", async (t) => { const connectionContexts = new WeakMap(); const beforePoolConnection = sinon.stub().callsFake((connectionContext) => { diff --git a/packages/slonik/src/binders/bindPool.ts b/packages/slonik/src/binders/bindPool.ts index a409e118..9ff0d0f4 100644 --- a/packages/slonik/src/binders/bindPool.ts +++ b/packages/slonik/src/binders/bindPool.ts @@ -232,7 +232,7 @@ export const bindPool = ( ); }, (newPool) => { - return newPool.transaction(transactionHandler); + return newPool.transaction(transactionHandler, transactionRetryLimit); }, ); }, diff --git a/packages/slonik/src/connectionMethods/oneFirst.test.ts b/packages/slonik/src/connectionMethods/oneFirst.test.ts index 36e7fa52..daa5e0f4 100644 --- a/packages/slonik/src/connectionMethods/oneFirst.test.ts +++ b/packages/slonik/src/connectionMethods/oneFirst.test.ts @@ -1,6 +1,6 @@ import { createPool } from "../factories/createPool.js"; import { createTestRunner } from "../helpers.test/createTestRunner.js"; -import { DataIntegrityError, NotFoundError, UnexpectedStateError } from "@slonik/errors"; +import { DataIntegrityError, NotFoundError } from "@slonik/errors"; import { createPgDriverFactory } from "@slonik/pg-driver"; import { createSqlTag } from "@slonik/sql-tag"; import { expectTypeOf } from "expect-type"; @@ -68,7 +68,8 @@ test("throws an error if more than one column is returned", async (t) => { `), ); - t.true(error instanceof UnexpectedStateError); + t.true(error instanceof DataIntegrityError); + t.is(error?.message, "Query returned rows with multiple columns."); }); test("describes zod object associated with the query", async (t) => { diff --git a/packages/slonik/src/connectionMethods/oneFirst.ts b/packages/slonik/src/connectionMethods/oneFirst.ts index 84454fad..8c1a082e 100644 --- a/packages/slonik/src/connectionMethods/oneFirst.ts +++ b/packages/slonik/src/connectionMethods/oneFirst.ts @@ -1,41 +1,25 @@ import type { InternalQueryMethod } from "../types.js"; -import { one } from "./one.js"; -import { UnexpectedStateError } from "@slonik/errors"; +import { query } from "./query.js"; import { generateUid } from "@slonik/utilities"; /** * Makes a query and expects exactly one result. * Returns value of the first column. * @throws NotFoundError If query returns no rows. - * @throws DataIntegrityError If query returns multiple rows. + * @throws DataIntegrityError If query returns multiple rows or multiple columns. */ export const oneFirst: InternalQueryMethod = async ( log, connection, clientConfiguration, - slonikSql, + slonikQuery, inheritedQueryId, ) => { const queryId = inheritedQueryId ?? generateUid(); - const row = await one(log, connection, clientConfiguration, slonikSql, queryId, { + const { rows } = await query(log, connection, clientConfiguration, slonikQuery, queryId, { validationType: "ONE_COLUMN", }); - const keys = Object.keys(row); - - if (keys.length > 1) { - log.error( - { - queryId, - }, - "DataIntegrityError", - ); - - throw new UnexpectedStateError( - "Expected query to return one result, but received multiple results.", - ); - } - - return row[keys[0]]; + return rows[0][Object.keys(rows[0])[0]]; }; diff --git a/packages/slonik/src/factories/createConnection.ts b/packages/slonik/src/factories/createConnection.ts index a31b2f5d..9c5f3521 100644 --- a/packages/slonik/src/factories/createConnection.ts +++ b/packages/slonik/src/factories/createConnection.ts @@ -12,7 +12,7 @@ import type { } from "../types.js"; import type { ConnectionPool, ConnectionPoolClient } from "./createConnectionPool.js"; import { SpanStatusCode, trace } from "@opentelemetry/api"; -import { UnexpectedStateError } from "@slonik/errors"; +import { DataIntegrityError, SchemaValidationError, UnexpectedStateError } from "@slonik/errors"; import type { QuerySqlToken } from "@slonik/sql-tag"; const tracer = trace.getTracer("slonik.interceptors"); @@ -195,21 +195,6 @@ export const createConnection = async ( throw error; } - let result; - - try { - result = await connectionHandler( - connectionLog, - connection, - boundConnection, - clientConfiguration, - ); - } catch (error) { - await connection.destroy(); - - throw error; - } - const releaseConnection = async () => { try { for (const interceptor of clientConfiguration.interceptors) { @@ -235,6 +220,30 @@ export const createConnection = async ( } }; + let result; + + try { + result = await connectionHandler( + connectionLog, + connection, + boundConnection, + clientConfiguration, + ); + } catch (error) { + // These errors describe the result of a query that succeeded, i.e. the connection is + // healthy. A routine passed to `connect()` can leave the connection in any state, though. + if ( + connectionType !== "EXPLICIT" && + (error instanceof DataIntegrityError || error instanceof SchemaValidationError) + ) { + releaseConnection().catch(() => {}); + } else { + await connection.destroy(); + } + + throw error; + } + releaseConnection().catch(() => {}); return result; diff --git a/packages/slonik/src/helpers.test/createIntegrationTests.ts b/packages/slonik/src/helpers.test/createIntegrationTests.ts index 5091f87b..66e0b445 100644 --- a/packages/slonik/src/helpers.test/createIntegrationTests.ts +++ b/packages/slonik/src/helpers.test/createIntegrationTests.ts @@ -1382,6 +1382,7 @@ export const createIntegrationTests = ( ); t.true(error instanceof InvalidInputError); + t.is((error?.cause as undefined | { code?: string })?.code, "22P02"); }); test("terminates transaction if any of the queries fails", async (t) => { diff --git a/packages/slonik/src/helpers.test/createPoolTests.ts b/packages/slonik/src/helpers.test/createPoolTests.ts index 197d6d6a..0b0e19a9 100644 --- a/packages/slonik/src/helpers.test/createPoolTests.ts +++ b/packages/slonik/src/helpers.test/createPoolTests.ts @@ -1,7 +1,15 @@ /* eslint-disable id-length */ /* cspell:ignore tstzrange */ -import { BackendTerminatedError, createPool, parseDsn, sql } from "../index.js"; +import { + BackendTerminatedError, + createPool, + DataIntegrityError, + NotFoundError, + parseDsn, + SchemaValidationError, + sql, +} from "../index.js"; import type { DatabasePoolConnection } from "../index.js"; import type { TestContextType } from "./createTestRunner.js"; import { waitForConnectionRelease } from "./waitForConnectionRelease.js"; @@ -486,6 +494,100 @@ export const createPoolTests = (test: TestFn, driverFactory: Dr t.not(firstConnectionPid, secondConnectionPid); }); + test("re-uses connection if a query result failed validation", async (t) => { + const pool = await createPool(t.context.dsn, { + driverFactory, + interceptors: [ + { + name: "schema-validation", + transformRow: (queryContext, query, row) => { + if (query.sql.includes("invalid_row")) { + throw new SchemaValidationError(query, row, []); + } + + return row; + }, + }, + ], + maxPoolSize: 1, + }); + + const firstConnectionPid = await pool.oneFirst(sql.unsafe` + SELECT pg_backend_pid(); + `); + + await t.throwsAsync(pool.one(sql.unsafe`SELECT 1 WHERE false`), { + instanceOf: NotFoundError, + }); + + await t.throwsAsync(pool.one(sql.unsafe`SELECT * FROM (VALUES (1), (2)) AS t(id)`), { + instanceOf: DataIntegrityError, + }); + + await t.throwsAsync(pool.query(sql.unsafe`SELECT 1 AS invalid_row`), { + instanceOf: SchemaValidationError, + }); + + const secondConnectionPid = await pool.oneFirst(sql.unsafe` + SELECT pg_backend_pid(); + `); + + t.is(firstConnectionPid, secondConnectionPid); + }); + + test("re-uses connection if a query result failed validation inside of a transaction", async (t) => { + const pool = await createPool(t.context.dsn, { + driverFactory, + maxPoolSize: 1, + }); + + const firstConnectionPid = await pool.oneFirst(sql.unsafe` + SELECT pg_backend_pid(); + `); + + await t.throwsAsync( + pool.transaction(async (transaction) => { + await transaction.one(sql.unsafe`SELECT 1 WHERE false`); + }), + { + instanceOf: NotFoundError, + }, + ); + + const secondConnectionPid = await pool.oneFirst(sql.unsafe` + SELECT pg_backend_pid(); + `); + + t.is(firstConnectionPid, secondConnectionPid); + }); + + test("does not re-use connection if a query result failed validation inside of connect()", async (t) => { + const pool = await createPool(t.context.dsn, { + driverFactory, + maxPoolSize: 1, + }); + + const firstConnectionPid = await pool.oneFirst(sql.unsafe` + SELECT pg_backend_pid(); + `); + + // The routine can leave the connection in any state, e.g. inside of a transaction. + await t.throwsAsync( + pool.connect(async (connection) => { + await connection.one(sql.unsafe`SELECT 1 WHERE false`); + }), + { + instanceOf: NotFoundError, + }, + ); + + const secondConnectionPid = await pool.oneFirst(sql.unsafe` + SELECT pg_backend_pid(); + `); + + t.not(firstConnectionPid, secondConnectionPid); + }); + test("queued connection gets a new connection in case a blocking connection produced an error", async (t) => { const pool = await createPool(t.context.dsn, { driverFactory, diff --git a/packages/slonik/src/types.ts b/packages/slonik/src/types.ts index 7adb1407..576fa94d 100644 --- a/packages/slonik/src/types.ts +++ b/packages/slonik/src/types.ts @@ -360,7 +360,6 @@ export type QueryContext = { export type QueryFunction = ( sql: QuerySqlToken, - values?: PrimitiveValueExpression[], ) => Promise>>; export type QueryId = string; @@ -447,46 +446,34 @@ type InferColumnValue = type QueryAnyFirstFunction = ( sql: QuerySqlToken, - values?: PrimitiveValueExpression[], ) => Promise>>; type QueryAnyFunction = ( sql: QuerySqlToken, - values?: PrimitiveValueExpression[], ) => Promise>>; -type QueryExistsFunction = ( - sql: QuerySqlToken, - values?: PrimitiveValueExpression[], -) => Promise; +type QueryExistsFunction = (sql: QuerySqlToken) => Promise; type QueryManyFirstFunction = ( sql: QuerySqlToken, - values?: PrimitiveValueExpression[], ) => Promise>>; type QueryManyFunction = ( sql: QuerySqlToken, - values?: PrimitiveValueExpression[], ) => Promise>>; type QueryMaybeOneFirstFunction = ( sql: QuerySqlToken, - values?: PrimitiveValueExpression[], ) => Promise | null>; type QueryMaybeOneFunction = ( sql: QuerySqlToken, - values?: PrimitiveValueExpression[], ) => Promise>; type QueryOneFirstFunction = ( sql: QuerySqlToken, - values?: PrimitiveValueExpression[], ) => Promise>; type QueryOneFunction = ( sql: QuerySqlToken, - values?: PrimitiveValueExpression[], ) => Promise>; type QueryRecordFunction = < T extends StandardSchemaV1, >( sql: QuerySqlToken, - values?: PrimitiveValueExpression[], ) => Promise< Readonly["key"], StandardSchemaV1.InferOutput["value"]>> >; From 018b197bdb2180fc8e2fda22b9862f34fd4c9f26 Mon Sep 17 00:00:00 2001 From: Gajus Date: Thu, 5 Nov 2026 15:06:51 -0800 Subject: [PATCH 2/3] feat: add retryLimit transaction option and use NOTE alerts for README notes --- .changeset/routed-transaction-retry-limit.md | 5 -- .changeset/transaction-options.md | 5 ++ README.md | 73 ++++++++++++------- .../interceptors/beforePoolConnection.test.ts | 10 ++- packages/slonik/src/binders/bindPool.ts | 7 +- .../slonik/src/binders/bindPoolConnection.ts | 5 +- .../src/binders/bindTransactionConnection.ts | 5 +- .../nestedTransaction.test.ts | 26 +++++++ .../src/connectionMethods/transaction.test.ts | 18 +++++ packages/slonik/src/index.ts | 1 + .../src/routines/getTransactionRetryLimit.ts | 11 +++ packages/slonik/src/types.ts | 19 ++++- 12 files changed, 141 insertions(+), 44 deletions(-) delete mode 100644 .changeset/routed-transaction-retry-limit.md create mode 100644 .changeset/transaction-options.md create mode 100644 packages/slonik/src/routines/getTransactionRetryLimit.ts diff --git a/.changeset/routed-transaction-retry-limit.md b/.changeset/routed-transaction-retry-limit.md deleted file mode 100644 index aa639f7b..00000000 --- a/.changeset/routed-transaction-retry-limit.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -"slonik": minor ---- - -fix: `pool.transaction(handler, transactionRetryLimit)` passes `transactionRetryLimit` to the pool returned by a `beforePoolConnection` interceptor. diff --git a/.changeset/transaction-options.md b/.changeset/transaction-options.md new file mode 100644 index 00000000..0d262463 --- /dev/null +++ b/.changeset/transaction-options.md @@ -0,0 +1,5 @@ +--- +"slonik": minor +--- + +add the `retryLimit` option to `transaction()`, e.g. `pool.transaction(handler, { retryLimit: 3 })`. Passing the retry limit as the second argument (`pool.transaction(handler, 3)`) is deprecated. Also fixes `pool.transaction()` dropping the retry limit when a `beforePoolConnection` interceptor returns another pool: the options are now passed to that pool. diff --git a/README.md b/README.md index 9660a55e..7c23dad0 100644 --- a/README.md +++ b/README.md @@ -463,7 +463,8 @@ Supported parameters: | `sslmode` | [`sslmode`](https://www.postgresql.org/docs/current/libpq-ssl.html#LIBPQ-SSL-PROTECTION) (supported values: `disable`, `no-verify`, `require`) | `disable` | | `sslrootcert` | The location of the [root certificate](<(https://www.postgresql.org/docs/current/libpq-ssl.html#LIBQ-SSL-CERTIFICATES)>) file. | | -Note that unless listed above, other [libpq parameters](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS) are not supported. +> [!NOTE] +> Unless listed above, other [libpq parameters](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-PARAMKEYWORDS) are not supported. Examples of valid DSNs: @@ -519,7 +520,8 @@ const pool = await createPool("postgres://", { }); ``` -> **Note:** If you are new to Slonik, then you should read [Integrating Slonik with Express.js](https://dev.to/gajus/integrating-slonik-with-expressjs-33kn). +> [!NOTE] +> If you are new to Slonik, then you should read [Integrating Slonik with Express.js](https://dev.to/gajus/integrating-slonik-with-expressjs-33kn). Instance of Slonik connection pool can be then used to create a new connection, e.g. @@ -566,7 +568,8 @@ const main = async () => { main(); ``` -Note: `pool.end()` does not terminate active connections/ transactions. +> [!NOTE] +> `pool.end()` does not terminate active connections/ transactions. ### Describing the current state of the connection pool @@ -633,7 +636,8 @@ const main = async () => { main(); ``` -Note: `pool.end()` does not terminate active connections/ transactions. +> [!NOTE] +> `pool.end()` does not terminate active connections/ transactions. ### API @@ -840,7 +844,8 @@ The primary difference between Slonik and `pg-promise`: - Slonik does not allow to execute raw text queries. Slonik queries can only be constructed using [`sql` tagged template literals](#tagged-template-literals). This design [protects against unsafe value interpolation](#protecting-against-unsafe-value-interpolation). - Slonik implements [interceptor API](#interceptors) (middleware). Middlewares allow to modify connection handling, override queries and modify the query results. Example Slonik interceptors include [field name transformation](https://github.com/gajus/slonik-interceptor-field-name-transformation), [query normalization](https://github.com/gajus/slonik-interceptor-query-normalisation) and [query benchmarking](https://github.com/gajus/slonik-interceptor-query-benchmarking). -Note: Author of `pg-promise` has [objected to the above claims](https://github.com/gajus/slonik/issues/122). I have removed a difference that was clearly wrong. I maintain that the above two differences remain valid differences: even though `pg-promise` might have substitute functionality for variable interpolation and interceptors, it implements them in a way that does not provide the same benefits that Slonik provides, namely: guaranteed security and support for extending library functionality using multiple plugins. +> [!NOTE] +> Author of `pg-promise` has [objected to the above claims](https://github.com/gajus/slonik/issues/122). I have removed a difference that was clearly wrong. I maintain that the above two differences remain valid differences: even though `pg-promise` might have substitute functionality for variable interpolation and interceptors, it implements them in a way that does not provide the same benefits that Slonik provides, namely: guaranteed security and support for extending library functionality using multiple plugins. Other differences are primarily in how the equivalent features are implemented, e.g. @@ -883,7 +888,8 @@ Example: } ``` -Note: Unlike [`pg-types`](https://github.com/brianc/node-pg-types) that uses OIDs to identify types, Slonik identifies types using their names. +> [!NOTE] +> Unlike [`pg-types`](https://github.com/brianc/node-pg-types) that uses OIDs to identify types, Slonik identifies types using their names. Use this query to find type names: @@ -1067,13 +1073,15 @@ pool.connect(); Executed after query has been executed and before rows were transformed using `transformRow`. -Note: Not executed for queries executed using `stream`. +> [!NOTE] +> Not executed for queries executed using `stream`. #### beforeQueryExecution 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`. +> [!NOTE] +> Not executed for queries executed using `stream`. #### beforeQueryResult @@ -1081,7 +1089,8 @@ Executed just before the result is returned to the client. Use this method to capture the result that will be returned to the client. -Note: Not executed for queries executed using `stream`. +> [!NOTE] +> Not executed for queries executed using `stream`. #### beforeTransformQuery @@ -1133,8 +1142,9 @@ Transforms row. Use `transformRow` to modify the query result. -Note: `transformRow` is synchronous. Use [`transformRowAsync`](#transformrowasync) if the -transformation is asynchronous. +> [!NOTE] +> `transformRow` is synchronous. Use [`transformRowAsync`](#transformrowasync) if the +> transformation is asynchronous. #### transformRowAsync @@ -1189,13 +1199,12 @@ On the other hand, `beforePoolConnection` makes it easy to route based on conven The first option is self-explanatory to implement, but this recipe demonstrates my convention for using `beforePoolConnection` to route queries. -Note: How you determine which queries are safe to route to a read-only instance is outside of scope for this documentation. - -Note: `beforePoolConnection` only works for connections initiated by a query, i.e. `pool#query` and not `pool#connect()`. - -Note: `pool#transaction` triggers `beforePoolConnection` but has no `query`. - -Note: This particular implementation does not handle [`SELECT INTO`](https://www.postgresql.org/docs/current/sql-selectinto.html). +> [!NOTE] +> +> - How you determine which queries are safe to route to a read-only instance is outside of scope for this documentation. +> - `beforePoolConnection` only works for connections initiated by a query, i.e. `pool#query` and not `pool#connect()`. +> - `pool#transaction` triggers `beforePoolConnection` but has no `query`. +> - This particular implementation does not handle [`SELECT INTO`](https://www.postgresql.org/docs/current/sql-selectinto.html). ```ts const readOnlyPool = await createPool("postgres://read-only"); @@ -1410,7 +1419,8 @@ Conversely you can allow unknown keys to be passed through by using [`.passthrou z.object({ foo: z.string() }).passthrough(); ``` -_Note_: Using `.passthrough()` is not recommended as it reduces type safety and may lead to unexpected behaviour. +> [!NOTE] +> Using `.passthrough()` is not recommended as it reduces type safety and may lead to unexpected behaviour. ### Handling schema validation errors @@ -2643,8 +2653,7 @@ const row = await connection.one(sql.typeAlias("foo")`SELECT foo`); // row.foo is the result of the `foo` column value of the first row. ``` -> Note: -> +> [!NOTE] > I've been asked "What makes this different from [knex.js](http://knexjs.org/) `knex('foo').limit(1)`?". > `knex('foo').limit(1)` simply generates "SELECT \* FROM foo LIMIT 1" query. > `knex` is a query builder; it does not assert the value of the result. @@ -2718,8 +2727,7 @@ const memberCounts = await connection.record(sql.type( Returns an empty object if query returns no rows. -> Note: -> +> [!NOTE] > `record` is not just a convenience method – it asserts the integrity of the result. > Building the record manually (e.g. using `Object.fromEntries`) silently drops rows > that share the same key, e.g. as a result of an incorrect `GROUP BY` clause. @@ -2877,7 +2885,21 @@ Transactions that are failing with [Transaction Rollback](https://www.postgresql A failing transaction will be rolled back and the callback function passed to the transaction method call will be executed again. Nested transactions are also retried until the retry limit is reached. If the nested transaction keeps failing with a [Transaction Rollback](https://www.postgresql.org/docs/current/errcodes-appendix.html) error, then the parent transaction will be retried until the retry limit is reached. -How many times a transaction is retried is controlled using `transactionRetryLimit` configuration (default: 5) and the `transactionRetryLimit` parameter of the `transaction` method (default: undefined). If a `transactionRetryLimit` is given to the method call then it is used otherwise the `transactionRetryLimit` configuration is used. +How many times a transaction is retried is controlled using `transactionRetryLimit` configuration (default: 5). Use the `retryLimit` option of the `transaction` method to override it for a transaction, e.g. + +```ts +await connection.transaction( + async (transactionConnection) => { + await transactionConnection.query(sql.unsafe`INSERT INTO foo (bar) VALUES ('baz')`); + }, + { + retryLimit: 3, + }, +); +``` + +> [!NOTE] +> Passing the retry limit as the second argument (`connection.transaction(handler, 3)`) is deprecated. #### Transaction events @@ -3244,7 +3266,8 @@ Query-level logging can be added using [`slonik-interceptor-query-logging`](http ### Capture stack trace -Note: Requires [`slonik-interceptor-query-logging`](https://github.com/gajus/slonik-interceptor-query-logging). +> [!NOTE] +> Requires [`slonik-interceptor-query-logging`](https://github.com/gajus/slonik-interceptor-query-logging). Enabling `captureStackTrace` configuration will create a stack trace before invoking the query and include the stack trace in the logs, e.g. diff --git a/packages/slonik/src/binders/bindPool.test/interceptors/beforePoolConnection.test.ts b/packages/slonik/src/binders/bindPool.test/interceptors/beforePoolConnection.test.ts index e7610b55..75e81b0f 100644 --- a/packages/slonik/src/binders/bindPool.test/interceptors/beforePoolConnection.test.ts +++ b/packages/slonik/src/binders/bindPool.test/interceptors/beforePoolConnection.test.ts @@ -30,7 +30,7 @@ test("`beforePoolConnection` is called before `connect`", async (t) => { t.true(beforePoolConnection.calledBefore(spy.acquire)); }); -test("`beforePoolConnection` that returns a pool runs the transaction using that pool, with the same retry limit", async (t) => { +test("`beforePoolConnection` that returns a pool runs the transaction using that pool, with the same options", async (t) => { const transaction = sinon.stub().resolves("foo"); const { pool } = await createPoolWithSpy(t.context.dsn, { @@ -51,8 +51,12 @@ test("`beforePoolConnection` that returns a pool runs the transaction using that return "bar"; }; - t.is(await pool.transaction(handler, 3), "foo"); - t.deepEqual(transaction.firstCall.args, [handler, 3]); + t.is(await pool.transaction(handler, { retryLimit: 3 }), "foo"); + t.deepEqual(transaction.firstCall.args, [handler, { retryLimit: 3 }]); + + // Deprecated: the retry limit as the second argument. + t.is(await pool.transaction(handler, 2), "foo"); + t.deepEqual(transaction.secondCall.args, [handler, 2]); }); test("pool connection lifecycle reuses the same context object", async (t) => { diff --git a/packages/slonik/src/binders/bindPool.ts b/packages/slonik/src/binders/bindPool.ts index 9ff0d0f4..68ba5181 100644 --- a/packages/slonik/src/binders/bindPool.ts +++ b/packages/slonik/src/binders/bindPool.ts @@ -1,6 +1,7 @@ import { transaction } from "../connectionMethods/transaction.js"; import { createConnection } from "../factories/createConnection.js"; import type { ConnectionPool } from "../factories/createConnectionPool.js"; +import { getTransactionRetryLimit } from "../routines/getTransactionRetryLimit.js"; import type { ClientConfiguration, DatabasePool, @@ -216,7 +217,7 @@ export const bindPool = ( streamQuery, ); }, - transaction: (transactionHandler, transactionRetryLimit) => { + transaction: (transactionHandler, options) => { return createConnection( parentLog, pool, @@ -228,11 +229,11 @@ export const bindPool = ( connection, clientConfiguration, transactionHandler, - transactionRetryLimit, + getTransactionRetryLimit(options), ); }, (newPool) => { - return newPool.transaction(transactionHandler, transactionRetryLimit); + return newPool.transaction(transactionHandler, options); }, ); }, diff --git a/packages/slonik/src/binders/bindPoolConnection.ts b/packages/slonik/src/binders/bindPoolConnection.ts index 23ae1505..68020d3d 100644 --- a/packages/slonik/src/binders/bindPoolConnection.ts +++ b/packages/slonik/src/binders/bindPoolConnection.ts @@ -12,6 +12,7 @@ import { record } from "../connectionMethods/record.js"; import { stream } from "../connectionMethods/stream.js"; import { transaction } from "../connectionMethods/transaction.js"; import type { ConnectionPoolClient } from "../factories/createConnectionPool.js"; +import { getTransactionRetryLimit } from "../routines/getTransactionRetryLimit.js"; import { getPoolClientState } from "../state.js"; import type { ClientConfiguration, DatabasePoolConnection, Logger } from "../types.js"; @@ -89,13 +90,13 @@ class BoundPoolConnection { ); } - transaction(handler, transactionRetryLimit) { + transaction(handler, options) { return transaction( this.parentLog, this.connection, this.clientConfiguration, handler, - transactionRetryLimit, + getTransactionRetryLimit(options), ); } } diff --git a/packages/slonik/src/binders/bindTransactionConnection.ts b/packages/slonik/src/binders/bindTransactionConnection.ts index b40ecd8b..bf11c1c0 100644 --- a/packages/slonik/src/binders/bindTransactionConnection.ts +++ b/packages/slonik/src/binders/bindTransactionConnection.ts @@ -12,6 +12,7 @@ import { query as queryMethod } from "../connectionMethods/query.js"; import { record } from "../connectionMethods/record.js"; import { stream } from "../connectionMethods/stream.js"; import type { ConnectionPoolClient } from "../factories/createConnectionPool.js"; +import { getTransactionRetryLimit } from "../routines/getTransactionRetryLimit.js"; import { getPoolClientState } from "../state.js"; import type { PoolClientState } from "../state.js"; import type { @@ -124,7 +125,7 @@ class BoundTransactionConnection { ); } - transaction(handler, transactionRetryLimit) { + transaction(handler, options) { this.assertTransactionDepth(); return nestedTransaction( this.parentLog, @@ -132,7 +133,7 @@ class BoundTransactionConnection { this.clientConfiguration, handler, this.transactionDepth, - transactionRetryLimit, + getTransactionRetryLimit(options), this.eventEmitter, this.transactionId, ); diff --git a/packages/slonik/src/connectionMethods/nestedTransaction.test.ts b/packages/slonik/src/connectionMethods/nestedTransaction.test.ts index 322c8d73..738fd2ee 100644 --- a/packages/slonik/src/connectionMethods/nestedTransaction.test.ts +++ b/packages/slonik/src/connectionMethods/nestedTransaction.test.ts @@ -115,6 +115,32 @@ test("returns the thrown transaction error if the retry limit is reached", async const handlerStub = sinon.stub(); + handlerStub + .onFirstCall() + .rejects(createErrorWithCode("40P01")) + .onSecondCall() + .rejects(createErrorWithCode("40P01")); + + const error: any = await t.throwsAsync( + pool.transaction( + async (transactionConnection) => { + return await transactionConnection.transaction(handlerStub, { retryLimit: 1 }); + }, + { retryLimit: 0 }, + ), + ); + + t.is(handlerStub.callCount, 2); + + t.true(error instanceof Error); + t.is(error?.code, "40P01"); +}); + +test("returns the thrown transaction error if the retry limit is reached (deprecated retry limit argument)", async (t) => { + const pool = await createPool(t.context.dsn); + + const handlerStub = sinon.stub(); + handlerStub .onFirstCall() .rejects(createErrorWithCode("40P01")) diff --git a/packages/slonik/src/connectionMethods/transaction.test.ts b/packages/slonik/src/connectionMethods/transaction.test.ts index 42a3e675..5c94b5a7 100644 --- a/packages/slonik/src/connectionMethods/transaction.test.ts +++ b/packages/slonik/src/connectionMethods/transaction.test.ts @@ -108,6 +108,24 @@ test("returns the thrown transaction error if the retry limit is reached", async const pool = await createPool(t.context.dsn); const handlerStub = sinon.stub(); + handlerStub + .onFirstCall() + .rejects(createErrorWithCode("40P01")) + .onSecondCall() + .rejects(createErrorWithCode("40P01")); + + const error: any = await t.throwsAsync(pool.transaction(handlerStub, { retryLimit: 1 })); + + t.is(handlerStub.callCount, 2); + + t.true(error instanceof Error); + t.is(error.code, "40P01"); +}); + +test("returns the thrown transaction error if the retry limit is reached (deprecated retry limit argument)", async (t) => { + const pool = await createPool(t.context.dsn); + const handlerStub = sinon.stub(); + handlerStub .onFirstCall() .rejects(createErrorWithCode("40P01")) diff --git a/packages/slonik/src/index.ts b/packages/slonik/src/index.ts index 5613e603..e5cb6cbb 100644 --- a/packages/slonik/src/index.ts +++ b/packages/slonik/src/index.ts @@ -36,6 +36,7 @@ export type { QueryResult, QueryResultRow, QueryResultRowColumn, + TransactionOptions, TypeNameIdentifier, ValueExpression, } from "./types.js"; diff --git a/packages/slonik/src/routines/getTransactionRetryLimit.ts b/packages/slonik/src/routines/getTransactionRetryLimit.ts new file mode 100644 index 00000000..2ec72267 --- /dev/null +++ b/packages/slonik/src/routines/getTransactionRetryLimit.ts @@ -0,0 +1,11 @@ +import type { TransactionOptions } from "../types.js"; + +/** + * Resolves the retry limit from the second argument of `transaction()`, which is either options + * or (deprecated) the retry limit. + */ +export const getTransactionRetryLimit = ( + options?: number | TransactionOptions, +): number | undefined => { + return typeof options === "number" ? options : options?.retryLimit; +}; diff --git a/packages/slonik/src/types.ts b/packages/slonik/src/types.ts index 576fa94d..be499280 100644 --- a/packages/slonik/src/types.ts +++ b/packages/slonik/src/types.ts @@ -138,10 +138,13 @@ export type CommonQueryMethods = { readonly query: QueryFunction; readonly record: QueryRecordFunction; readonly stream: StreamFunction; - readonly transaction: ( - handler: TransactionFunction, - transactionRetryLimit?: number, - ) => Promise; + readonly transaction: { + (handler: TransactionFunction, options?: TransactionOptions): Promise; + /** + * @deprecated Use `transaction(handler, { retryLimit })` instead. + */ + (handler: TransactionFunction, transactionRetryLimit?: number): Promise; + }; }; export type Connection = "EXPLICIT" | "IMPLICIT_QUERY" | "IMPLICIT_TRANSACTION"; @@ -384,6 +387,14 @@ export type StreamResult = { readonly type: "StreamResult"; }; +export type TransactionOptions = { + /** + * Number of times the transaction is retried if it fails with a Transaction Rollback class + * error. (Default: `transactionRetryLimit` of the client configuration) + */ + readonly retryLimit?: number; +}; + /** * "string" type covers all type name identifiers – the literal values are added only to assist developer * experience with auto suggestions for commonly used type name identifiers. From 622ae0611cf39e91772be8202d9970813f29bc66 Mon Sep 17 00:00:00 2001 From: Gajus Date: Thu, 5 Nov 2026 15:32:45 -0800 Subject: [PATCH 3/3] fix: reject stream() with interceptor errors and close the cursor of failed streams --- .changeset/stream-errors.md | 6 + README.md | 2 + .../src/factories/createPgDriverFactory.ts | 9 ++ .../slonik/src/connectionMethods/stream.ts | 29 ++-- .../slonik/src/factories/createConnection.ts | 5 +- .../helpers.test/createIntegrationTests.ts | 124 +++++++++++++++++- packages/slonik/src/types.ts | 2 +- 7 files changed, 165 insertions(+), 12 deletions(-) create mode 100644 .changeset/stream-errors.md diff --git a/.changeset/stream-errors.md b/.changeset/stream-errors.md new file mode 100644 index 00000000..cf59dec4 --- /dev/null +++ b/.changeset/stream-errors.md @@ -0,0 +1,6 @@ +--- +"@slonik/pg-driver": minor +"slonik": minor +--- + +fix: `stream()` rejects with the error of a `transformRow` or `transformRowAsync` interceptor (e.g. a `SchemaValidationError` of a result parser). Previously, the error was an unhandled rejection, `stream()` never settled, and the connection was never released. `stream()` also waits for the promise returned by the stream handler (e.g. an `async` function that uses `for await`). When the consumer of a stream fails, the driver closes the cursor, so that the connection can be used again (e.g. to roll back the transaction). diff --git a/README.md b/README.md index 7c23dad0..e17e006c 100644 --- a/README.md +++ b/README.md @@ -2779,6 +2779,8 @@ await connection.stream(sql.typeAlias("foo")`SELECT foo`, async (stream) => { }); ``` +If the function passed to `stream` returns a promise (e.g. it is an `async` function), `stream` waits for the promise. If the stream fails (e.g. because an interceptor fails to transform a row), `stream` rejects with the error. + ### transaction `transaction` method is used wrap execution of queries in `START TRANSACTION` and `COMMIT` or `ROLLBACK`. `COMMIT` is called if the transaction handler returns a promise that resolves; `ROLLBACK` is called otherwise. diff --git a/packages/pg-driver/src/factories/createPgDriverFactory.ts b/packages/pg-driver/src/factories/createPgDriverFactory.ts index 3dc13660..6fc724e8 100644 --- a/packages/pg-driver/src/factories/createPgDriverFactory.ts +++ b/packages/pg-driver/src/factories/createPgDriverFactory.ts @@ -447,6 +447,15 @@ export const createPgDriverFactory = (): DriverFactory => { }); stream.pipe(transform); + + // `pipe` does not destroy the query stream when `transform` is destroyed (e.g. because + // the consumer failed to process a row). That would leave the cursor open and block + // every subsequent query of the connection; destroying the query stream closes it. + transform.once("close", () => { + if (!stream.destroyed) { + stream.destroy(); + } + }); }; const typeParsers = streamOptions?.typeParsers; diff --git a/packages/slonik/src/connectionMethods/stream.ts b/packages/slonik/src/connectionMethods/stream.ts index 1c0524e6..0d4bbdb8 100644 --- a/packages/slonik/src/connectionMethods/stream.ts +++ b/packages/slonik/src/connectionMethods/stream.ts @@ -54,13 +54,20 @@ const createTransformStream = ( let finalRow = datum.row as QueryResultRow; - // apply row transformers. Note this is done sequentially, as one transformer's result will be passed to the next. - for (const rowTransformer of rowTransformers) { - finalRow = rowTransformer(queryContext, query, finalRow, datum.fields); - } + // Node.js ignores the promise returned by `transform`, so errors must be passed to `callback`. + try { + // apply row transformers. Note this is done sequentially, as one transformer's result will be passed to the next. + for (const rowTransformer of rowTransformers) { + finalRow = rowTransformer(queryContext, query, finalRow, datum.fields); + } - for (const rowTransformer of asyncRowTransformers) { - finalRow = await rowTransformer(queryContext, query, finalRow, datum.fields); + for (const rowTransformer of asyncRowTransformers) { + finalRow = await rowTransformer(queryContext, query, finalRow, datum.fields); + } + } catch (error) { + callback(error); + + return; } this.push({ @@ -107,10 +114,16 @@ const createExecutionRoutine = ( transformStream.once("finish", resolve); }); - onStream(transformStream); + // The handler can be an async function (e.g. one that consumes the stream using `for await`), + // which rejects when the stream fails. Waiting for it reports that rejection through + // `stream()` instead of leaving it unhandled. + const handlerPromise = Promise.resolve(onStream(transformStream)); try { - await Promise.race([pipeline(queryStream, transformStream), streamErrorPromise]); + await Promise.all([ + Promise.race([pipeline(queryStream, transformStream), streamErrorPromise]), + handlerPromise, + ]); } catch (error) { if (streamDestroyError) { queryStream.destroy(); diff --git a/packages/slonik/src/factories/createConnection.ts b/packages/slonik/src/factories/createConnection.ts index 9c5f3521..8369cd31 100644 --- a/packages/slonik/src/factories/createConnection.ts +++ b/packages/slonik/src/factories/createConnection.ts @@ -230,8 +230,9 @@ export const createConnection = async ( clientConfiguration, ); } catch (error) { - // These errors describe the result of a query that succeeded, i.e. the connection is - // healthy. A routine passed to `connect()` can leave the connection in any state, though. + // These errors describe the result of a query (e.g. a row that failed validation), i.e. the + // connection is healthy (the cursor of a failed stream is closed by the driver). A routine + // passed to `connect()` can leave the connection in any state, though. if ( connectionType !== "EXPLICIT" && (error instanceof DataIntegrityError || error instanceof SchemaValidationError) diff --git a/packages/slonik/src/helpers.test/createIntegrationTests.ts b/packages/slonik/src/helpers.test/createIntegrationTests.ts index 66e0b445..15b50fea 100644 --- a/packages/slonik/src/helpers.test/createIntegrationTests.ts +++ b/packages/slonik/src/helpers.test/createIntegrationTests.ts @@ -14,6 +14,7 @@ import { InvalidInputError, NotNullIntegrityConstraintViolationError, runOutsideTransaction, + SchemaValidationError, sql, StatementCancelledError, StatementTimeoutError, @@ -22,7 +23,13 @@ import { UnexpectedStateError, UniqueIntegrityConstraintViolationError, } from "../index.js"; -import type { DatabaseTransactionConnection, DriverTypeParser } from "../index.js"; +import type { + DatabaseTransactionConnection, + DriverTypeParser, + Interceptor, + Query, + QueryResultRow, +} from "../index.js"; import { createErrorWithCode } from "./createErrorWithCode.js"; import type { TestContextType } from "./createTestRunner.js"; import { waitForConnectionRelease } from "./waitForConnectionRelease.js"; @@ -190,6 +197,121 @@ export const createIntegrationTests = ( t.is(await pool.oneFirst(sql.unsafe`SELECT count(*)::int4 FROM person`), 1); }); + // Fails to process the row with `id` 2, like a result parser interceptor does for an invalid row. + const createFailRowInterceptor = ( + interceptorMethod: "transformRow" | "transformRowAsync", + ): Interceptor => { + const failRow = (query: Query, row: QueryResultRow) => { + if (row.id === 2) { + throw new SchemaValidationError(query, row, []); + } + + return row; + }; + + return interceptorMethod === "transformRow" + ? { + name: "fail-row", + transformRow: (queryContext, query, row) => { + return failRow(query, row); + }, + } + : { + name: "fail-row", + transformRowAsync: async (queryContext, query, row) => { + return failRow(query, row); + }, + }; + }; + + const failingStreamQuery = sql.unsafe`SELECT generate_series(1, 10000) AS id`; + + for (const [interceptorMethod, consumer] of [ + ["transformRow", "data event listener"], + ["transformRowAsync", "data event listener"], + ["transformRow", "async iterator"], + ] as const) { + test(`stream rejects with the error of a ${interceptorMethod} interceptor (${consumer})`, async (t) => { + const pool = await createPool(t.context.dsn, { + driverFactory, + interceptors: [createFailRowInterceptor(interceptorMethod)], + maxPoolSize: 1, + }); + + const firstConnectionPid = await pool.oneFirst(sql.unsafe`SELECT pg_backend_pid()`); + + await t.throwsAsync( + consumer === "data event listener" + ? pool.stream(failingStreamQuery, (stream) => { + stream.on("data", () => {}); + }) + : pool.stream(failingStreamQuery, async (stream) => { + for await (const row of stream) { + t.truthy(row); + } + }), + { + instanceOf: SchemaValidationError, + }, + ); + + // The connection is returned to the pool (the stream is closed) and can be used again. + t.is(await pool.oneFirst(sql.unsafe`SELECT pg_backend_pid()`), firstConnectionPid); + + t.deepEqual(await pool.anyFirst(sql.unsafe`SELECT generate_series(1, 3)`), [1, 2, 3]); + + await pool.end(); + }); + } + + test("rolls back a transaction in which a stream failed to process a row", async (t) => { + const pool = await createPool(t.context.dsn, { + driverFactory, + interceptors: [createFailRowInterceptor("transformRow")], + maxPoolSize: 1, + }); + + await t.throwsAsync( + pool.transaction(async (transaction) => { + await transaction.query(sql.unsafe`INSERT INTO person (name) VALUES ('foo')`); + + await transaction.stream(failingStreamQuery, (stream) => { + stream.on("data", () => {}); + }); + }), + { + instanceOf: SchemaValidationError, + }, + ); + + t.is(await pool.oneFirst(sql.unsafe`SELECT count(*)::int4 FROM person`), 0); + + await pool.end(); + }); + + test("runs queries using a connection after a stream failed to process a row", async (t) => { + const pool = await createPool(t.context.dsn, { + driverFactory, + interceptors: [createFailRowInterceptor("transformRow")], + maxPoolSize: 1, + }); + + await pool.connect(async (connection) => { + await t.throwsAsync( + connection.stream(failingStreamQuery, (stream) => { + stream.on("data", () => {}); + }), + { + instanceOf: SchemaValidationError, + }, + ); + + t.is(await connection.oneFirst(sql.unsafe`SELECT 1`), 1); + }); + + await pool.end(); + }); + test("streams data", async (t) => { const pool = await createPool(t.context.dsn, { driverFactory, diff --git a/packages/slonik/src/types.ts b/packages/slonik/src/types.ts index be499280..0735975d 100644 --- a/packages/slonik/src/types.ts +++ b/packages/slonik/src/types.ts @@ -380,7 +380,7 @@ export type QueryResultRow = Record; export type QueryResultRowColumn = PrimitiveValueExpression; -export type StreamHandler = (stream: DriverStream) => void; +export type StreamHandler = (stream: DriverStream) => MaybePromise; export type StreamResult = { readonly notices: readonly DriverNotice[];