@voxpelli/pg-utils 3.1.0 → 4.0.0

package/README.md

@@ -13,11 +13,7 @@ My personal database utils / helpers for Postgres
 ## Usage
 
 ```javascript
-import {
-  csvFromFolderToDb,
-  dbToCsvFolder,
-  PgTestHelpers,
-} from '@voxpelli/pg-utils';
+import { PgTestHelpers } from '@voxpelli/pg-utils';
 
 const pgHelpers = new PgTestHelpers({
   connectionString: 'postgres://user:pass@localhost/example',
@@ -31,18 +27,47 @@ const pgHelpers = new PgTestHelpers({
 });
 
 try {
-  // The helper automatically acquires an exclusive database lock
-  // on the first call to initTables(), insertFixtures(), or removeTables()
-  // to prevent concurrent access between tests during test operations.
   await pgHelpers.initTables();
   await pgHelpers.insertFixtures();
 } finally {
-  // Always release the lock and close connections,
-  // even if a test or setup step throws an error
   await pgHelpers.end();
 }
 ```
 
+Or use `pgTestSetup` / `pgTestSetupFor` for one-step setup with automatic cleanup:
+
+```javascript
+import { pgTestSetupFor } from '@voxpelli/pg-utils';
+
+// With node:test — cleanup registered via t.after()
+it('inserts a record', async (t) => {
+  const helpers = await pgTestSetupFor({
+    connectionString: 'postgres://user:pass@localhost/example',
+    schema: new URL('./create-tables.sql', import.meta.url),
+    fixtureFolder: new URL('./fixtures', import.meta.url),
+  }, t);
+
+  // Tables created, fixtures loaded.
+  // helpers.end() called automatically after test via t.after()
+});
+```
+
+```javascript
+import { pgTestSetup } from '@voxpelli/pg-utils';
+
+// With await using — cleanup via Symbol.asyncDispose
+it('inserts a record', async () => {
+  await using helpers = await pgTestSetup({
+    connectionString: 'postgres://user:pass@localhost/example',
+    schema: new URL('./create-tables.sql', import.meta.url),
+    fixtureFolder: new URL('./fixtures', import.meta.url),
+  });
+
+  // Tables created, fixtures loaded.
+  // helpers.end() called automatically when scope exits.
+});
+```
+
 ## PgTestHelpers
 
 Class that creates a helpers instance
@@ -71,22 +96,180 @@ new PgTestHelpers({
 
 * `connectionString` – _`string`_ – a connection string for the postgres database
 * `fixtureFolder` – _`[string | URL]`_ – _optional_ – the path to a folder of `.csv`-file fixtures named by their respective table
+* `idleInTransactionTimeoutMs` – _`[number]`_ – _optional_ – idle-in-transaction session timeout in milliseconds, applied to pool connections. Auto-kills transactions left open by crashed tests.
 * `ignoreTables` – _`[string[]]`_ – _optional_ – names of tables to ignore when dropping
-* `schema` – _`string | URL | Umzug`_ – an umzug instance that can be used to initialize tables or the schema itself or a `URL` to a text file containing the schema
+* `lockId` – _`[number]`_ – _optional_ – advisory lock ID (default: `42`). All instances with the same `lockId` on the same PostgreSQL cluster serialize against each other — this is the intended isolation behavior that prevents concurrent test operations from interfering. Since `removeTables()` drops all public tables (not just the ones defined in `schema`), using different lock IDs only makes sense when test files target entirely separate databases (see [Parallel Test Runners](#parallel-test-runners)).
+* `lockTimeoutMs` – _`[number]`_ – _optional_ – lock acquisition timeout in milliseconds. When set, a `SET lock_timeout` is issued before acquiring the advisory lock. If another process holds the lock longer than this, the acquisition fails with a descriptive error instead of waiting indefinitely.
+* `schema` – _`string | URL | ((pool: pg.Pool) => Umzug)`_ – a factory function that receives the pool and returns an Umzug instance, or the schema itself as a string, or a `URL` to a text file containing the schema
+* `statementTimeoutMs` – _`[number]`_ – _optional_ – per-statement query timeout in milliseconds, applied to pool connections. Prevents any single query from hanging indefinitely.
 * `tableLoadOrder` – _`[Array<string[] | string>]`_ – _optional_ – tables in parent-first insertion order: the first item is loaded first and dropped last. Use nested arrays to group tables that can be dropped in parallel. Mutually exclusive with `tablesWithDependencies`.
 * `tablesWithDependencies` – _`[Array<string[] | string>]`_ – _optional_ – **Deprecated:** use `tableLoadOrder` instead. Tables in leaf-first deletion order: the first item is dropped first and loaded last.
 
 ### Methods
 
+* `setup() => Promise<this>` – convenience method that runs the standard sequence: `removeTables()`, `initTables()`, and `insertFixtures()` (when `fixtureFolder` is set). Returns `this` so it can be chained with `await using`. Calls `end()` internally on failure to prevent pool leaks.
 * `initTables() => Promise<void>` – sets up all of the tables. Automatically acquires an exclusive database lock on first call.
 * `insertFixtures() => Promise<void>` – inserts all the fixtures data into the tables (only usable if `fixtureFolder` has been set). Automatically acquires an exclusive database lock on first call.
-* `removeTables() => Promise<void>` – removes all of the tables (respecting `tableLoadOrder` / `tablesWithDependencies` ordering). Automatically acquires an exclusive database lock on first call.
+* `removeTables() => Promise<void>` – removes all of the tables (respecting `tableLoadOrder` / `tablesWithDependencies` ordering). Automatically acquires an exclusive database lock on first call. **Note:** this drops all tables in the `public` schema, not just those defined in `schema`.
 * `end() => Promise<void>` – releases the database lock (if acquired) and closes all database connections. **Always call this when done** to properly clean up resources.
+* `queryPromise` – _`Pool['query']`_ – bound reference to the underlying `pg.Pool.query()` method for ad-hoc SQL queries in tests.
+* `[Symbol.asyncDispose]() => Promise<void>` – alias for `end()`. Enables `await using` syntax for automatic cleanup.
 
 #### Database Locking
 
 The `PgTestHelpers` class uses [PostgreSQL advisory locks](https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS) to ensure exclusive database access during test operations. The lock is automatically acquired on the first call to `initTables()`, `insertFixtures()`, or `removeTables()`, and is held until `end()` is called. This prevents multiple test suites from interfering with each other when using the same database.
 
+Advisory locks are **cluster-scoped** — all connections to the same PostgreSQL cluster (even to different databases) that use the same `lockId` will serialize against each other. The default `lockId` of `42` ensures all `PgTestHelpers` instances coordinate, which is normally what you want.
+
+#### Parallel Test Runners
+
+When using `node:test` or other parallel test runners, all test files share the same database and the same advisory lock (ID `42`). This means they serialize — which is correct, since `removeTables()` drops all public tables and concurrent drops would corrupt each other's state.
+
+If your test files truly need parallel execution, consider using separate databases per test file and setting a unique `lockId` per database.
+
+## pgTestSetup()
+
+Creates and sets up a `PgTestHelpers` instance in one step. Use with `await using` for automatic cleanup.
+
+### Syntax
+
+```ts
+pgTestSetup(options) => Promise<PgTestHelpers>
+```
+
+### Arguments
+
+* `options` – _[`PgTestHelpersOptions`](#pgtesthelpersoptions)_ – same options as the `PgTestHelpers` constructor
+
+## pgTestSetupFor()
+
+Creates and sets up a `PgTestHelpers` instance, registering cleanup via `t.after()`. No `await using` or `afterEach` needed.
+
+### Syntax
+
+```ts
+pgTestSetupFor(options, t) => Promise<PgTestHelpers>
+```
+
+### Arguments
+
+* `options` – _[`PgTestHelpersOptions`](#pgtesthelpersoptions)_ – same options as the `PgTestHelpers` constructor
+* `t` – _`{ after?: Function }`_ – a test context with an `after()` method (e.g., node:test's `TestContext`). Cleanup is registered via `t.after(() => helpers.end())`. Throws `TypeError` if `after` is missing.
+
+## Using with node:test
+
+### Per-test with `pgTestSetupFor` (recommended)
+
+The simplest pattern. `pgTestSetupFor` creates and sets up the helpers, then registers cleanup via `t.after()` — no `afterEach` or `await using` needed:
+
+```javascript
+import { describe, it } from 'node:test';
+import { pgTestSetupFor } from '@voxpelli/pg-utils';
+
+describe('my feature', () => {
+  it('inserts a record', async (t) => {
+    const helpers = await pgTestSetupFor({
+      connectionString: process.env.DATABASE_URL,
+      schema: new URL('./schema.sql', import.meta.url),
+    }, t);
+
+    // Tables are ready. helpers.end() called automatically via t.after()
+  });
+});
+```
+
+### Per-test with `await using`
+
+When you prefer scope-based cleanup or your test framework doesn't expose a test context:
+
+```javascript
+import { describe, it } from 'node:test';
+import { pgTestSetup } from '@voxpelli/pg-utils';
+
+describe('my feature', () => {
+  it('inserts a record', async () => {
+    await using helpers = await pgTestSetup({
+      connectionString: process.env.DATABASE_URL,
+      schema: new URL('./schema.sql', import.meta.url),
+    });
+
+    // Tables are ready. helpers.end() called automatically on scope exit.
+  });
+});
+```
+
+**Trade-off:** each test pays the full setup cost (drop + create + load fixtures). For suites with many tests against the same fixture data, use `beforeEach` with `pgTestSetupFor` instead.
+
+### Suite-level with `beforeEach` + `pgTestSetupFor`
+
+Use `pgTestSetupFor` inside `beforeEach` when the `helpers` reference is needed across multiple tests. The `t.after()` registration eliminates the need for a separate `afterEach` for helpers cleanup:
+
+```javascript
+import assert from 'node:assert/strict';
+import { beforeEach, describe, it } from 'node:test';
+import { pgTestSetupFor } from '@voxpelli/pg-utils';
+
+describe('my feature', () => {
+  /** @type {import('@voxpelli/pg-utils').PgTestHelpers} */
+  let helpers;
+
+  beforeEach(async (t) => {
+    helpers = await pgTestSetupFor({
+      connectionString: process.env.DATABASE_URL,
+      schema: new URL('./schema.sql', import.meta.url),
+      fixtureFolder: new URL('./fixtures', import.meta.url),
+    }, t);
+  });
+
+  it('reads a record', async () => {
+    const { rows } = await helpers.queryPromise('SELECT 1 AS val');
+    assert.strictEqual(rows[0]?.val, 1);
+  });
+});
+```
+
+`setup()` calls `end()` internally on failure, so no `try/catch` is needed in `beforeEach`. If you need additional cleanup beyond helpers (e.g., `app.close()`), add an `afterEach` for that.
+
+## Factory pattern
+
+For projects with multiple test files sharing the same database configuration, centralise setup in a factory function:
+
+```javascript
+// tools/test-helpers.js
+import { pgTestSetupFor } from '@voxpelli/pg-utils';
+
+/** @param {{ after?: (fn: () => Promise<void>) => void }} t */
+export const testSetup = (t) => pgTestSetupFor({
+  connectionString: process.env.DATABASE_URL,
+  schema: new URL('../schema.sql', import.meta.url),
+  fixtureFolder: new URL('../test/fixtures', import.meta.url),
+  tableLoadOrder: [
+    'accounts',
+    ['posts', 'comments'],
+  ],
+}, t);
+```
+
+Test files become minimal:
+
+```javascript
+import { beforeEach, describe, it } from 'node:test';
+import { testSetup } from '../tools/test-helpers.js';
+
+describe('posts', () => {
+  /** @type {import('@voxpelli/pg-utils').PgTestHelpers} */
+  let helpers;
+
+  beforeEach(async (t) => {
+    helpers = await testSetup(t);
+  });
+
+  // No afterEach needed — cleanup registered via t.after()
+
+  // ... tests using helpers.queryPromise ...
+});
+```
+
 ## csvFromFolderToDb()
 
 Imports data into tables from a folder of CSV files. All files will be imported and they should named by their table names + `.csv`.
@@ -125,21 +308,8 @@ dbToCsvFolder(connection, outputPath, tables, [options]) => Promise<void>
 * `outputPath` – _`string | URL`_ – the directory to write CSV files into (created if it does not exist)
 * `tables` – _`string[]`_ – explicit list of table names to export
 * `options` – _`object`_ – _optional_
-  * `orderBy` – _`string`_ – SQL `ORDER BY` expression for deterministic output (default: `'1'`, i.e. the first column)
+  * `orderBy` – _`string`_ – column index (e.g. `'1'`) or simple identifier (e.g. `'created_at'`) for deterministic output ordering (default: `'1'`, i.e. the first column). Expressions, `ASC`/`DESC`, and multi-column values are not accepted.
 
 ### Returns
 
 `Promise` that resolves on completion
-
-<!-- ## Used by
-
-* [`example`](https://example.com/) – used by this one to do X and Y
-
-## Similar modules
-
-* [`example`](https://example.com/) – is similar in this way
-
-## See also
-
-* [Announcement blog post](#)
-* [Announcement tweet](#) -->

package/index.d.ts

@@ -1,4 +1,4 @@
 export { csvFromFolderToDb } from "./lib/csv-folder-to-db.js";
 export { dbToCsvFolder } from "./lib/db-to-csv-folder.js";
-export { PgTestHelpers } from "./lib/test-helpers.js";
+export { PgTestHelpers, pgTestSetup, pgTestSetupFor } from "./lib/test-helpers.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,3 +1,3 @@
 export { csvFromFolderToDb } from './lib/csv-folder-to-db.js';
 export { dbToCsvFolder } from './lib/db-to-csv-folder.js';
-export { PgTestHelpers } from './lib/test-helpers.js';
+export { PgTestHelpers, pgTestSetup, pgTestSetupFor } from './lib/test-helpers.js';

package/lib/csv-folder-to-db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"csv-folder-to-db.d.ts","sourceRoot":"","sources":["csv-folder-to-db.js"],"names":[],"mappings":"AAkHA,8CALW,MAAM,GAAG,IAAI,QACb,MAAM,GAAG,GAAG,YACZ,MAAM,EAAE,GAAG,wBAAwB,GACjC,OAAO,CAAC,IAAI,CAAC,CA2BzB;;qBA1Ea,MAAM,EAAE;6BACR,MAAM,EAAE;;0BAvDI,IAAI"}
+{"version":3,"file":"csv-folder-to-db.d.ts","sourceRoot":"","sources":["csv-folder-to-db.js"],"names":[],"mappings":"AAkHA,8CALW,MAAM,GAAG,IAAI,QACb,MAAM,GAAG,GAAG,YACZ,MAAM,EAAE,GAAG,wBAAwB,GACjC,OAAO,CAAC,IAAI,CAAC,CAgCzB;;qBA/Ea,MAAM,EAAE;6BACR,MAAM,EAAE;;0BAvDI,IAAI"}

package/lib/csv-folder-to-db.js

@@ -116,25 +116,30 @@ export async function csvFromFolderToDb (connection, path, options) {
   const tablesWithDependencies = resolveTableOrder(options);
   const files = await getFilesOrderedByDependencies(path, tablesWithDependencies);
 
-  const pool = (typeof connection === 'object' && 'connect' in connection) ? connection : createPgPool(connection);
-
-  const client = await pool.connect();
+  const ownPool = typeof connection !== 'object' || !('connect' in connection);
+  const pool = ownPool ? createPgPool(connection) : connection;
 
   try {
-    for (const file of files) {
-      const name = pathModule.basename(file, '.csv');
-      const dbCopy = client.query(copyFrom(`COPY ${pg.escapeIdentifier(name)} FROM STDIN WITH (FORMAT csv, HEADER MATCH)`));
+    const client = await pool.connect();
+
+    try {
+      for (const file of files) {
+        const name = pathModule.basename(file, '.csv');
+        const dbCopy = client.query(copyFrom(`COPY ${pg.escapeIdentifier(name)} FROM STDIN WITH (FORMAT csv, HEADER MATCH)`));
 
-      // eslint-disable-next-line security/detect-non-literal-fs-filename
-      const csvContent = createReadStream(file);
+        // eslint-disable-next-line security/detect-non-literal-fs-filename
+        const csvContent = createReadStream(file);
 
-      try {
-        await promisedPipeline(csvContent, dbCopy);
-      } catch (cause) {
-        throw new Error(`Failed inserting data into "${name}"`, { cause });
+        try {
+          await promisedPipeline(csvContent, dbCopy);
+        } catch (cause) {
+          throw new Error(`Failed inserting data into "${name}"`, { cause });
+        }
       }
+    } finally {
+      client.release();
     }
   } finally {
-    client.release();
+    if (ownPool) await pool.end();
   }
 }

package/lib/db-to-csv-folder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db-to-csv-folder.d.ts","sourceRoot":"","sources":["db-to-csv-folder.js"],"names":[],"mappings":"AA8BA,0CANW,MAAM,GAAG,IAAI,cACb,MAAM,GAAG,GAAG,UACZ,MAAM,EAAE,YACR,oBAAoB,GAClB,OAAO,CAAC,IAAI,CAAC,CA0BzB;;cAvCa,MAAM;;0BAJM,IAAI"}
+{"version":3,"file":"db-to-csv-folder.d.ts","sourceRoot":"","sources":["db-to-csv-folder.js"],"names":[],"mappings":"AA8BA,0CANW,MAAM,GAAG,IAAI,cACb,MAAM,GAAG,GAAG,UACZ,MAAM,EAAE,YACR,oBAAoB,GAClB,OAAO,CAAC,IAAI,CAAC,CAgDzB;;cA7Da,MAAM;;0BAJM,IAAI"}

package/lib/db-to-csv-folder.js

@@ -31,25 +31,47 @@ import { createPgPool } from './utils.js';
 export async function dbToCsvFolder (connection, outputPath, tables, options = {}) {
   const { orderBy = '1' } = options;
 
+  // Security: orderBy is interpolated into SQL — validate to prevent injection
+  const isColumnIndex = /^[1-9]\d*$/.test(orderBy);
+  const isIdentifier = /^[a-z_]\w*$/i.test(orderBy);
+
+  if (!isColumnIndex && !isIdentifier) {
+    throw new Error(
+      `Invalid orderBy value: ${JSON.stringify(orderBy)}. ` +
+      'Must be a positive column index (e.g. "1") or a simple identifier (e.g. "created_at").'
+    );
+  }
+
   const dirPath = typeof outputPath === 'string' ? outputPath : fileURLToPath(outputPath);
 
   // eslint-disable-next-line security/detect-non-literal-fs-filename
   await mkdir(dirPath, { recursive: true });
 
-  const pool = (typeof connection === 'object' && 'connect' in connection) ? connection : createPgPool(connection);
+  const escapedOrderBy = isColumnIndex ? orderBy : pg.escapeIdentifier(orderBy);
 
-  const client = await pool.connect();
+  const ownPool = typeof connection !== 'object' || !('connect' in connection);
+  const pool = ownPool ? createPgPool(connection) : connection;
 
   try {
-    for (const table of tables) {
-      const sql = `COPY (SELECT * FROM ${pg.escapeIdentifier(table)} ORDER BY ${orderBy}) TO STDOUT WITH (FORMAT csv, HEADER true)`;
-      const copyToStream = client.query(copyTo(sql));
-      const filePath = pathModule.join(dirPath, `${table}.csv`);
+    const client = await pool.connect();
+
+    try {
+      for (const table of tables) {
+        const sql = `COPY (SELECT * FROM ${pg.escapeIdentifier(table)} ORDER BY ${escapedOrderBy}) TO STDOUT WITH (FORMAT csv, HEADER true)`;
+        const copyToStream = client.query(copyTo(sql));
+        const filePath = pathModule.join(dirPath, `${table}.csv`);
 
-      // eslint-disable-next-line security/detect-non-literal-fs-filename
-      await pipeline(copyToStream, createWriteStream(filePath));
+        try {
+          // eslint-disable-next-line security/detect-non-literal-fs-filename
+          await pipeline(copyToStream, createWriteStream(filePath));
+        } catch (cause) {
+          throw new Error(`Failed exporting data from "${table}"`, { cause });
+        }
+      }
+    } finally {
+      client.release();
     }
   } finally {
-    client.release();
+    if (ownPool) await pool.end();
   }
 }

package/lib/test-helpers.d.ts

@@ -1,16 +1,26 @@
+export function pgTestSetup(options: PgTestHelpersOptions): Promise<PgTestHelpers>;
+export function pgTestSetupFor(options: PgTestHelpersOptions, t: {
+    after?: (fn: () => Promise<void>) => void;
+}): Promise<PgTestHelpers>;
 export class PgTestHelpers {
     constructor(options: PgTestHelpersOptions);
     queryPromise: Pool["query"];
     initTables(): Promise<void>;
     insertFixtures(): Promise<void>;
+    setup(): Promise<this>;
     removeTables(): Promise<void>;
     end(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     #private;
 }
 export type PgTestHelpersOptions = {
     connectionString: string;
     fixtureFolder?: string | URL;
     ignoreTables?: string[];
+    lockId?: number;
+    lockTimeoutMs?: number;
+    statementTimeoutMs?: number;
+    idleInTransactionTimeoutMs?: number;
     schema: string | URL | ((pool: Pool) => import("umzug").Umzug<import("umzeption").UmzeptionContext<"pg", import("umzeption").FastifyPostgresStyleDb>>);
     tableLoadOrder?: Array<string[] | string>;
     tablesWithDependencies?: Array<string[] | string>;

package/lib/test-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["test-helpers.js"],"names":[],"mappings":"AAuBA;IAuBE,qBADY,oBAAoB,EAoD/B;IAtDD,cADW,IAAI,CAAC,OAAO,CAAC,CACX;IA8Hb,cADc,OAAO,CAAC,IAAI,CAAC,CAmB1B;IAGD,kBADc,OAAO,CAAC,IAAI,CAAC,CAkB1B;IAGD,gBADc,OAAO,CAAC,IAAI,CAAC,CAgB1B;IAGD,OADc,OAAO,CAAC,IAAI,CAAC,CAO1B;;CACF;;sBA5Na,MAAM;oBACN,MAAM,GAAG,GAAG;mBACZ,MAAM,EAAE;YACR,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,OAAO,EAAE,KAAK,CAAC,OAAO,WAAW,EAAE,gBAAgB,CAAC,IAAI,EAAE,OAAO,WAAW,EAAE,sBAAsB,CAAC,CAAC,CAAC;qBAC9I,KAAK,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC;6BACxB,KAAK,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC;;0BATJ,IAAI"}
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["test-helpers.js"],"names":[],"mappings":"AA8UA,qCAHW,oBAAoB,GAClB,OAAO,CAAC,aAAa,CAAC,CAIlC;AAgBD,wCAJW,oBAAoB,KACpB;IAAE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,IAAI,CAAA;CAAE,GAC3C,OAAO,CAAC,aAAa,CAAC,CAUlC;AA7UD;IA2BE,qBADY,oBAAoB,EAsF/B;IAxFD,cADW,IAAI,CAAC,OAAO,CAAC,CACX;IAqKb,cADc,OAAO,CAAC,IAAI,CAAC,CAoB1B;IAGD,kBADc,OAAO,CAAC,IAAI,CAAC,CAuB1B;IASD,SAFa,OAAO,CAAC,IAAI,CAAC,CAgBzB;IAGD,gBADc,OAAO,CAAC,IAAI,CAAC,CAqB1B;IAGD,OADc,OAAO,CAAC,IAAI,CAAC,CAW1B;IAGD,yBADc,OAAO,CAAC,IAAI,CAAC,CAG1B;;CACF;;sBAtTa,MAAM;oBACN,MAAM,GAAG,GAAG;mBACZ,MAAM,EAAE;aACR,MAAM;oBACN,MAAM;yBACN,MAAM;iCACN,MAAM;YACN,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,OAAO,EAAE,KAAK,CAAC,OAAO,WAAW,EAAE,gBAAgB,CAAC,IAAI,EAAE,OAAO,WAAW,EAAE,sBAAsB,CAAC,CAAC,CAAC;qBAC9I,KAAK,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC;6BACxB,KAAK,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC;;0BAbJ,IAAI"}

package/lib/test-helpers.js

@@ -16,6 +16,10 @@ import { createPgPool, createAndLockConnection, releaseLock, isStringArray, Type
  * @property {string} connectionString
  * @property {string | URL} [fixtureFolder]
  * @property {string[]} [ignoreTables]
+ * @property {number} [lockId] Advisory lock ID. Default: 42. Use unique IDs per test file for parallel runners (advisory locks are cluster-scoped).
+ * @property {number} [lockTimeoutMs] Lock acquisition timeout in milliseconds. No default (waits indefinitely).
+ * @property {number} [statementTimeoutMs] Per-statement query timeout in milliseconds on the pool. No default.
+ * @property {number} [idleInTransactionTimeoutMs] Idle-in-transaction timeout in milliseconds. No default.
  * @property {string | URL | ((pool: Pool) => import('umzug').Umzug<import('umzeption').UmzeptionContext<'pg', import('umzeption').FastifyPostgresStyleDb>>)} schema
  * @property {Array<string[] | string>} [tableLoadOrder] Tables in parent-first insertion order. First item loaded first, dropped last. Mutually exclusive with `tablesWithDependencies`.
  * @property {Array<string[] | string>} [tablesWithDependencies] Deprecated: use `tableLoadOrder` instead. Tables in leaf-first deletion order. First item dropped first, loaded last.
@@ -30,6 +34,10 @@ export class PgTestHelpers {
   #fixtureFolder;
   /** @type {string[] | undefined} */
   #ignoreTables;
+  /** @type {number} */
+  #lockId;
+  /** @type {number | undefined} */
+  #lockTimeoutMs;
   /** @type {Pool} */
   #pool;
   /** @type {Promise<Client> | Client | undefined} */
@@ -52,8 +60,12 @@ export class PgTestHelpers {
     const {
       connectionString,
       fixtureFolder,
+      idleInTransactionTimeoutMs,
       ignoreTables,
+      lockId = 42,
+      lockTimeoutMs,
       schema,
+      statementTimeoutMs,
       tableLoadOrder,
       tablesWithDependencies,
     } = options;
@@ -79,9 +91,37 @@ export class PgTestHelpers {
     if (tablesWithDependencies && !Array.isArray(tablesWithDependencies)) {
       throw new TypeNeverError(tablesWithDependencies, 'Invalid tablesWithDependencies, expected an array');
     }
+    if (lockId !== undefined && (typeof lockId !== 'number' || !Number.isSafeInteger(lockId))) {
+      throw new TypeError('Invalid lockId, expected a safe integer');
+    }
+    if (lockTimeoutMs !== undefined && (typeof lockTimeoutMs !== 'number' || !Number.isSafeInteger(lockTimeoutMs) || lockTimeoutMs < 0)) {
+      throw new TypeError('Invalid lockTimeoutMs, expected a non-negative safe integer');
+    }
+    if (statementTimeoutMs !== undefined && (typeof statementTimeoutMs !== 'number' || !Number.isSafeInteger(statementTimeoutMs) || statementTimeoutMs < 0)) {
+      throw new TypeError('Invalid statementTimeoutMs, expected a non-negative safe integer');
+    }
+    if (idleInTransactionTimeoutMs !== undefined && (typeof idleInTransactionTimeoutMs !== 'number' || !Number.isSafeInteger(idleInTransactionTimeoutMs) || idleInTransactionTimeoutMs < 0)) {
+      throw new TypeError('Invalid idleInTransactionTimeoutMs, expected a non-negative safe integer');
+    }
 
     const pool = createPgPool(connectionString);
 
+    // Set pool-level timeouts via 'connect' event. pg.Client serializes queries
+    // internally, so the SET completes before any caller query even though the
+    // callback return value is not awaited by pg-pool.
+    if (statementTimeoutMs !== undefined) {
+      pool.on('connect', (/** @type {import('pg').PoolClient} */ client) => {
+        // eslint-disable-next-line promise/prefer-await-to-then
+        client.query(`SET statement_timeout = ${Number(statementTimeoutMs)}`).catch(() => {});
+      });
+    }
+    if (idleInTransactionTimeoutMs !== undefined) {
+      pool.on('connect', (/** @type {import('pg').PoolClient} */ client) => {
+        // eslint-disable-next-line promise/prefer-await-to-then
+        client.query(`SET idle_in_transaction_session_timeout = ${Number(idleInTransactionTimeoutMs)}`).catch(() => {});
+      });
+    }
+
     // tableLoadOrder is parent-first; reverse to get the leaf-first
     // order that internal methods expect (drop first item first, load last)
     this.#tablesWithDependencies = tableLoadOrder
@@ -92,6 +132,8 @@ export class PgTestHelpers {
     this.#connectionString = connectionString;
     this.#fixtureFolder = fixtureFolder;
     this.#ignoreTables = ignoreTables;
+    this.#lockId = lockId;
+    this.#lockTimeoutMs = lockTimeoutMs;
     this.#pool = pool;
     this.#schema = schema;
     this.queryPromise = pool.query.bind(pool);
@@ -145,8 +187,11 @@ export class PgTestHelpers {
     }
 
     if (!this.#lockClient) {
+      this.#lockClient = createAndLockConnection(this.#connectionString, {
+        lockId: this.#lockId,
+        ...this.#lockTimeoutMs !== undefined && { lockTimeoutMs: this.#lockTimeoutMs },
       // eslint-disable-next-line promise/prefer-await-to-then
-      this.#lockClient = createAndLockConnection(this.#connectionString).then(result => {
+      }).then(result => {
         this.#lockClient = result;
         return result;
       }, (err) => {
@@ -160,9 +205,11 @@ export class PgTestHelpers {
 
   /** @returns {Promise<void>} */
   async #releaseLocked () {
-    if (this.#lockClient) {
-      await releaseLock(this.#lockClient);
+    const lockClient = this.#lockClient;
+
+    if (lockClient) {
       this.#lockClient = undefined;
+      await releaseLock(lockClient, this.#lockId);
     }
   }
 
@@ -183,6 +230,7 @@ export class PgTestHelpers {
 
       return pgInstallSchemaFromString(createUmzeptionPgContext(this.#pool), schema);
     } catch (cause) {
+      try { await this.#releaseLocked(); } catch {}
       throw new Error('Failed to create tables', { cause });
     }
   }
@@ -204,25 +252,58 @@ export class PgTestHelpers {
       options = { tablesWithDependencies: this.#tablesWithDependencies.flat() };
     }
 
-    return csvFromFolderToDb(this.#pool, this.#fixtureFolder, options);
+    try {
+      await csvFromFolderToDb(this.#pool, this.#fixtureFolder, options);
+    } catch (cause) {
+      try { await this.#releaseLocked(); } catch {}
+      throw new Error('Failed to import fixtures', { cause });
+    }
+  }
+
+  /**
+   * Convenience method for the standard test setup sequence: remove existing
+   * tables, create the schema, and optionally load fixtures (when `fixtureFolder`
+   * is configured). Returns `this` so the result can be used with `await using`.
+   *
+   * @returns {Promise<this>}
+   */
+  async setup () {
+    try {
+      await this.removeTables();
+      await this.initTables();
+
+      if (this.#fixtureFolder) {
+        await this.insertFixtures();
+      }
+    } catch (cause) {
+      try { await this.end(); } catch {}
+      throw cause;
+    }
+
+    return this;
   }
 
   /** @returns {Promise<void>} */
   async removeTables () {
     await this.#ensureLocked();
 
-    if (this.#tablesWithDependencies) {
-      await this.#removeTablesByName(this.#tablesWithDependencies);
-    }
+    try {
+      if (this.#tablesWithDependencies) {
+        await this.#removeTablesByName(this.#tablesWithDependencies);
+      }
 
-    let tableNames = await this.#getTableNames();
-    const ignoreTables = this.#ignoreTables;
+      let tableNames = await this.#getTableNames();
+      const ignoreTables = this.#ignoreTables;
 
-    if (ignoreTables) {
-      tableNames = tableNames.filter(name => !ignoreTables.includes(name));
-    }
+      if (ignoreTables) {
+        tableNames = tableNames.filter(name => !ignoreTables.includes(name));
+      }
 
-    await this.#removeTablesByName(tableNames);
+      await this.#removeTablesByName(tableNames);
+    } catch (cause) {
+      try { await this.#releaseLocked(); } catch {}
+      throw new Error('Failed to remove tables', { cause });
+    }
   }
 
   /** @returns {Promise<void>} */
@@ -230,7 +311,51 @@ export class PgTestHelpers {
     if (this.#ended) return;
 
     this.#ended = true;
-    await this.#releaseLocked();
-    await this.#pool.end();
+
+    try {
+      await this.#releaseLocked();
+    } finally {
+      await this.#pool.end();
+    }
   }
+
+  /** @returns {Promise<void>} */
+  async [Symbol.asyncDispose] () {
+    await this.end();
+  }
+}
+
+/**
+ * Create and set up a {@link PgTestHelpers} instance for use with `await using`.
+ * Cleanup happens automatically via `Symbol.asyncDispose` on scope exit.
+ *
+ * @param {PgTestHelpersOptions} options
+ * @returns {Promise<PgTestHelpers>}
+ */
+export async function pgTestSetup (options) {
+  return new PgTestHelpers(options).setup();
+}
+
+/**
+ * Create and set up a {@link PgTestHelpers} instance with cleanup registered
+ * on a test context via `t.after()`. No `await using` or `afterEach` needed.
+ *
+ * Useful in `node:test` `it()` bodies and `beforeEach()` hooks where `t`
+ * provides the test context. The `t` parameter uses duck-typing with `after`
+ * optional so it accepts node:test's `TestContext | SuiteContext` union from
+ * `beforeEach` hooks. At runtime, `beforeEach` always passes `TestContext`
+ * (which has `after`). A clear error is thrown if `after` is missing.
+ *
+ * @param {PgTestHelpersOptions} options
+ * @param {{ after?: (fn: () => Promise<void>) => void }} t Test context.
+ * @returns {Promise<PgTestHelpers>}
+ */
+export async function pgTestSetupFor (options, t) {
+  if (typeof t?.after !== 'function') {
+    throw new TypeError('pgTestSetupFor requires a test context with an after() method');
+  }
+
+  const helpers = await new PgTestHelpers(options).setup();
+  t.after(() => helpers.end());
+  return helpers;
 }

package/lib/utils.d.ts

@@ -1,6 +1,9 @@
 export function createPgPool(connectionString: string): Pool;
-export function createAndLockConnection(connectionString: string): Promise<Client>;
-export function releaseLock(lockClient: Client | Promise<Client>): Promise<void>;
+export function createAndLockConnection(connectionString: string, options?: {
+    lockId?: number;
+    lockTimeoutMs?: number;
+}): Promise<Client>;
+export function releaseLock(lockClient: Client | Promise<Client>, lockId?: number): Promise<void>;
 export function isStringArray(value: unknown): value is string[];
 export class TypeNeverError extends TypeError {
     constructor(value: never, message: string, options?: ErrorOptions);

package/lib/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.js"],"names":[],"mappings":"AAqBA,+CAHW,MAAM,GACJ,IAAI,CAOhB;AAMD,0DAHW,MAAM,GACJ,OAAO,CAAC,MAAM,CAAC,CAqB3B;AAMD,wCAHW,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,GACtB,OAAO,CAAC,IAAI,CAAC,CAUzB;AA4BD,qCAHW,OAAO,GACL,KAAK,IAAI,MAAM,EAAE,CAK7B;AA5BD;IAME,mBAJW,KAAK,WACL,MAAM,YACN,YAAY,EAItB;CACF;0BA3EiC,IAAI;4BAAJ,IAAI"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.js"],"names":[],"mappings":"AAuBA,+CAHW,MAAM,GACJ,IAAI,CAOhB;AAOD,0DAJW,MAAM,YACN;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,GACzC,OAAO,CAAC,MAAM,CAAC,CAwC3B;AAOD,wCAJW,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,WACxB,MAAM,GACJ,OAAO,CAAC,IAAI,CAAC,CAUzB;AA4BD,qCAHW,OAAO,GACL,KAAK,IAAI,MAAM,EAAE,CAK7B;AA5BD;IAME,mBAJW,KAAK,WACL,MAAM,YACN,YAAY,EAItB;CACF;0BAlGiC,IAAI;4BAAJ,IAAI"}

package/lib/utils.js

@@ -3,12 +3,14 @@ import pg from 'pg';
 /** @import { Pool, Client } from 'pg' */
 
 /**
- * Fixed advisory lock ID used for database locking (test isolation) during test runs.
- * By using a fixed ID (42), we serialize operations that
+ * Default advisory lock ID used for database locking (test isolation) during test runs.
+ * By using a fixed default ID (42), we serialize operations that
  * must not run concurrently (such as schema migrations or fixture loading), preventing race
  * conditions and deadlocks in test environments.
  *
- * The value 42 is arbitrary but must be consistent across all test helpers using the same database.
+ * This can be overridden via the `lockId` option in {@link createAndLockConnection} or
+ * `PgTestHelpersOptions` to avoid contention in parallel test runners (advisory locks are
+ * cluster-scoped, not database-scoped).
  *
  * @see {@link https://www.postgresql.org/docs/current/functions-admin.html#FUNCTIONS-ADVISORY-LOCKS|PostgreSQL Advisory Lock Functions}
  * @see {@link https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS|Advisory Locks Overview}
@@ -28,9 +30,19 @@ export function createPgPool (connectionString) {
 
 /**
  * @param {string} connectionString
+ * @param {{ lockId?: number, lockTimeoutMs?: number }} [options]
  * @returns {Promise<Client>}
  */
-export async function createAndLockConnection (connectionString) {
+export async function createAndLockConnection (connectionString, options = {}) {
+  const { lockId = LOCK_ID, lockTimeoutMs } = options;
+
+  if (lockId !== undefined && (typeof lockId !== 'number' || !Number.isSafeInteger(lockId))) {
+    throw new TypeError('Invalid lockId, expected a safe integer');
+  }
+  if (lockTimeoutMs !== undefined && (typeof lockTimeoutMs !== 'number' || !Number.isSafeInteger(lockTimeoutMs) || lockTimeoutMs < 0)) {
+    throw new TypeError('Invalid lockTimeoutMs, expected a non-negative safe integer');
+  }
+
   const client = new pg.Client({
     connectionString,
   });
@@ -40,7 +52,10 @@ export async function createAndLockConnection (connectionString) {
   try {
     await client.connect();
     connected = true;
-    await client.query('SELECT pg_advisory_lock($1)', [LOCK_ID]);
+    if (lockTimeoutMs !== undefined) {
+      await client.query(`SET lock_timeout = ${lockTimeoutMs}`);
+    }
+    await client.query('SELECT pg_advisory_lock($1)', [lockId]);
   } catch (cause) {
     if (connected) {
       await client.end();
@@ -48,18 +63,26 @@ export async function createAndLockConnection (connectionString) {
     throw new Error('Failed to acquire database lock', { cause });
   }
 
+  // Prevent uncaught 'error' event crash if the connection drops while holding
+  // the lock. PostgreSQL auto-releases session-level locks on disconnect, so
+  // the lock is already lost — end() will handle pool cleanup. Operations use
+  // the pool (not the lock client), so they continue to work; only the
+  // serialization guarantee is gone.
+  client.on('error', () => {});
+
   return client;
 }
 
 /**
  * @param {Client | Promise<Client>} lockClient
+ * @param {number} [lockId]
  * @returns {Promise<void>}
  */
-export async function releaseLock (lockClient) {
+export async function releaseLock (lockClient, lockId = LOCK_ID) {
   const client = await lockClient;
 
   try {
-    await client.query('SELECT pg_advisory_unlock($1)', [LOCK_ID]);
+    await client.query('SELECT pg_advisory_unlock($1)', [lockId]);
   } finally {
     await client.end();
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxpelli/pg-utils",
-  "version": "3.1.0",
+  "version": "4.0.0",
   "description": " My personal database utils / helpers for Postgres",
   "homepage": "http://github.com/voxpelli/pg-utils",
   "repository": {
@@ -11,7 +11,7 @@
   "author": "Pelle Wessman <pelle@kodfabrik.se> (http://kodfabrik.se/)",
   "license": "MIT",
   "engines": {
-    "node": "^20.9.0 || >=22.0.0"
+    "node": ">=22.0.0"
   },
   "type": "module",
   "exports": "./index.js",
@@ -48,7 +48,7 @@
     "@types/chai": "^4.3.20",
     "@types/chai-as-promised": "^7.1.8",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^20.19.33",
+    "@types/node": "^22.19.15",
     "@types/pg-copy-streams": "^1.2.5",
     "@types/sinon": "^21.0.0",
     "@voxpelli/eslint-config": "^23.0.0",
@@ -57,13 +57,14 @@
     "chai": "^4.5.0",
     "chai-as-promised": "^7.1.2",
     "dotenv": "^17.3.1",
-    "eslint": "^9.39.2",
+    "eslint": "^9.39.4",
     "husky": "^9.1.7",
-    "installed-check": "^10.0.0",
-    "knip": "^5.84.0",
+    "installed-check": "^10.0.1",
+    "knip": "^5.86.0",
     "mocha": "^11.7.5",
     "npm-run-all2": "^8.0.4",
-    "sinon": "^21.0.1",
+    "pony-cause": "^2.1.11",
+    "sinon": "^21.0.2",
     "type-coverage": "^2.29.7",
     "typescript": "~5.9.3",
     "validate-conventional-commit": "^1.0.4"