@voxpelli/pg-utils 2.3.0 → 3.0.0

package/README.md

@@ -27,6 +27,18 @@ const pgHelpers = new PgTestHelpers({
     ['foo', 'bar'],
   ]
 });
+
+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();
+}
 ```
 
 ## PgTestHelpers
@@ -55,7 +67,7 @@ new PgTestHelpers({
 
 ### PgTestHelpersOptions
 
-* `connectionString` – _`string | _ – a connection string for the postgres database
+* `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
 * `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
@@ -63,9 +75,14 @@ new PgTestHelpers({
 
 ### Methods
 
-* `initTables() => Promise<void>` – sets up all of the tables
-* `insertFixtures() => Promise<void>` – inserts all the fixtures data into the tables (only usable if `fixtureFolder` has been set)
-* `removeTables() => Promise<void>` – removes all of the tables (starting with `tablesWithDependencies`)
+* `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 (starting with `tablesWithDependencies`). Automatically acquires an exclusive database lock on first call.
+* `end() => Promise<void>` – releases the database lock (if acquired) and closes all database connections. **Always call this when done** to properly clean up resources.
+
+#### 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.
 
 ## csvFromFolderToDb()
 

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

@@ -1 +1 @@
-{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["test-helpers.js"],"names":[],"mappings":"AAqBA;IAeE,qBADY,oBAAoB,EAsC/B;IAxCD,cADW,IAAI,CAAC,OAAO,CAAC,CACX;IAyEb,cADc,OAAO,CAAC,IAAI,CAAC,CAiB1B;IAGD,kBADc,OAAO,CAAC,IAAI,CAAC,CAM1B;IAGD,gBADc,OAAO,CAAC,IAAI,CAAC,CAc1B;IAGD,OADc,OAAO,CAAC,IAAI,CAAC,CAG1B;;CACF;;sBA1Ia,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;6BAC9I,KAAK,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC;;0BARZ,IAAI"}
+{"version":3,"file":"test-helpers.d.ts","sourceRoot":"","sources":["test-helpers.js"],"names":[],"mappings":"AAqBA;IAqBE,qBADY,oBAAoB,EAuC/B;IAzCD,cADW,IAAI,CAAC,OAAO,CAAC,CACX;IA8Gb,cADc,OAAO,CAAC,IAAI,CAAC,CAmB1B;IAGD,kBADc,OAAO,CAAC,IAAI,CAAC,CAS1B;IAGD,gBADc,OAAO,CAAC,IAAI,CAAC,CAgB1B;IAGD,OADc,OAAO,CAAC,IAAI,CAAC,CAO1B;;CACF;;sBAhMa,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;6BAC9I,KAAK,CAAC,MAAM,EAAE,GAAG,MAAM,CAAC;;0BARJ,IAAI"}

package/lib/test-helpers.js

@@ -6,9 +6,9 @@ import {
 } from 'umzeption';
 
 import { csvFromFolderToDb } from './csv-folder-to-db.js';
-import { createPgPool, isStringArray, TypeNeverError } from './utils.js';
+import { createPgPool, createAndLockConnection, releaseLock, isStringArray, TypeNeverError } from './utils.js';
 
-/** @import { Pool } from 'pg' */
+/** @import { Pool, Client } from 'pg' */
 
 /**
  * @typedef PgTestHelpersOptions
@@ -20,12 +20,18 @@ import { createPgPool, isStringArray, TypeNeverError } from './utils.js';
  */
 
 export class PgTestHelpers {
+  /** @type {string} */
+  #connectionString;
+  /** @type {boolean} */
+  #ended = false;
   /** @type {string | URL | undefined} */
   #fixtureFolder;
   /** @type {string[] | undefined} */
   #ignoreTables;
   /** @type {Pool} */
   #pool;
+  /** @type {Promise<Client> | Client | undefined} */
+  #lockClient;
   /** @type {PgTestHelpersOptions['schema']} */
   #schema;
   /** @type {Array<string[] | string> | undefined} */
@@ -65,6 +71,7 @@ export class PgTestHelpers {
 
     const pool = createPgPool(connectionString);
 
+    this.#connectionString = connectionString;
     this.#fixtureFolder = fixtureFolder;
     this.#ignoreTables = ignoreTables;
     this.#tablesWithDependencies = tablesWithDependencies;
@@ -81,10 +88,11 @@ export class PgTestHelpers {
 
   /**
    * @param {Array<string[] | string>} tables
+   * @param {boolean} [allowParallelRemoval]
    * @returns {Promise<void>}
    */
-  async #removeTablesByName (tables) {
-    if (isStringArray(tables)) {
+  async #removeTablesByName (tables, allowParallelRemoval = false) {
+    if (allowParallelRemoval && isStringArray(tables)) {
       await Promise.all(
         tables.map(name => this.queryPromise('DROP TABLE IF EXISTS ' + name + ' CASCADE'))
       ).catch(cause => {
@@ -94,7 +102,7 @@ export class PgTestHelpers {
       for (const name of tables) {
         await (
           Array.isArray(name)
-            ? this.#removeTablesByName(name)
+            ? this.#removeTablesByName(name, true)
             : this.queryPromise('DROP TABLE IF EXISTS ' + name + ' CASCADE').catch(cause => {
               throw new Error(`Failed to drop table: ${name}`, { cause });
             })
@@ -103,8 +111,45 @@ export class PgTestHelpers {
     }
   }
 
+  /**
+   * Acquire an advisory lock used by this helper to serialize access with other
+   * code that uses the same locking mechanism.
+   *
+   * This does not block all other database operations: only code paths that
+   * acquire the same advisory lock ID via {@link createAndLockConnection} will
+   * be prevented from proceeding concurrently. The lock is held until
+   * {@link end} is called.
+   *
+   * @returns {Promise<Client>}
+   */
+  async #ensureLocked () {
+    if (this.#ended) {
+      throw new Error('This PgTestHelpers instance has been ended through .end() and can not be used any more.');
+    }
+
+    if (!this.#lockClient) {
+      // eslint-disable-next-line promise/prefer-await-to-then
+      this.#lockClient = createAndLockConnection(this.#connectionString).then(result => {
+        this.#lockClient = result;
+        return result;
+      });
+    }
+
+    return this.#lockClient;
+  }
+
+  /** @returns {Promise<void>} */
+  async #releaseLocked () {
+    if (this.#lockClient) {
+      await releaseLock(this.#lockClient);
+      this.#lockClient = undefined;
+    }
+  }
+
   /** @returns {Promise<void>} */
   async initTables () {
+    await this.#ensureLocked();
+
     try {
       if (typeof this.#schema === 'function') {
         await this.#schema(this.#pool).up();
@@ -127,11 +172,16 @@ export class PgTestHelpers {
     if (!this.#fixtureFolder) {
       throw new Error('No fixture folder defined');
     }
+
+    await this.#ensureLocked();
+
     return csvFromFolderToDb(this.#pool, this.#fixtureFolder, this.#tablesWithDependencies?.flat());
   }
 
   /** @returns {Promise<void>} */
   async removeTables () {
+    await this.#ensureLocked();
+
     if (this.#tablesWithDependencies) {
       await this.#removeTablesByName(this.#tablesWithDependencies);
     }
@@ -148,6 +198,10 @@ export class PgTestHelpers {
 
   /** @returns {Promise<void>} */
   async end () {
+    if (this.#ended) return;
+
+    this.#ended = true;
+    await this.#releaseLocked();
     await this.#pool.end();
   }
 }

package/lib/utils.d.ts

@@ -1,6 +1,10 @@
-export function createPgPool(connectionString: string): import("pg").Pool;
+export function createPgPool(connectionString: string): Pool;
+export function createAndLockConnection(connectionString: string): Promise<Client>;
+export function releaseLock(lockClient: Client | Promise<Client>): Promise<void>;
 export function isStringArray(value: unknown): value is string[];
 export class TypeNeverError extends TypeError {
     constructor(value: never, message: string, options?: ErrorOptions);
 }
+import type { Pool } from 'pg';
+import type { Client } from 'pg';
 //# sourceMappingURL=utils.d.ts.map

package/lib/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.js"],"names":[],"mappings":"AAMA,+CAHW,MAAM,GACJ,OAAO,IAAI,EAAE,IAAI,CAO7B;AA4BD,qCAHW,OAAO,GACL,KAAK,IAAI,MAAM,EAAE,CAK7B;AA5BD;IAME,mBAJW,KAAK,WACL,MAAM,YACN,YAAY,EAItB;CACF"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["utils.js"],"names":[],"mappings":"AAsBA,+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;0BA5EiC,IAAI;4BAAJ,IAAI"}

package/lib/utils.js

@@ -1,8 +1,24 @@
 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
+ * 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.
+ *
+ * @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}
+
+ */
+const LOCK_ID = 42;
+
 /**
  * @param {string} connectionString
- * @returns {import('pg').Pool}
+ * @returns {Pool}
  */
 export function createPgPool (connectionString) {
   return new pg.Pool({
@@ -11,6 +27,45 @@ export function createPgPool (connectionString) {
   });
 }
 
+/**
+ * @param {string} connectionString
+ * @returns {Promise<Client>}
+ */
+export async function createAndLockConnection (connectionString) {
+  const client = new pg.Client({
+    connectionString,
+  });
+
+  let connected = false;
+
+  try {
+    await client.connect();
+    connected = true;
+    await client.query('SELECT pg_advisory_lock($1)', [LOCK_ID]);
+  } catch (cause) {
+    if (connected) {
+      await client.end();
+    }
+    throw new Error('Failed to acquire database lock', { cause });
+  }
+
+  return client;
+}
+
+/**
+ * @param {Client | Promise<Client>} lockClient
+ * @returns {Promise<void>}
+ */
+export async function releaseLock (lockClient) {
+  const client = await lockClient;
+
+  try {
+    await client.query('SELECT pg_advisory_unlock($1)', [LOCK_ID]);
+  } finally {
+    await client.end();
+  }
+}
+
 // TODO: Export to typed-utils maybe?
 export class TypeNeverError extends TypeError {
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voxpelli/pg-utils",
-  "version": "2.3.0",
+  "version": "3.0.0",
   "description": " My personal database utils / helpers for Postgres",
   "homepage": "http://github.com/voxpelli/pg-utils",
   "repository": {
@@ -37,7 +37,8 @@
     "clean:declarations-top": "rm -rf $(find . -maxdepth 1 -type f -name '*.d.ts*' ! -name 'index.d.ts')",
     "clean:declarations-lib": "rm -rf $(find lib -type f -name '*.d.ts*' ! -name '*-types.d.ts')",
     "clean": "run-p clean:*",
-    "prepare": "husky",
+    "husky-enable": "husky",
+    "husky-disable": "git config --unset core.hooksPath",
     "prepublishOnly": "run-s build",
     "test:mocha": "c8 --reporter=lcov --reporter=text mocha 'test/**/*.spec.js'",
     "test-ci": "run-s test:*",
@@ -47,28 +48,30 @@
     "@types/chai": "^4.3.20",
     "@types/chai-as-promised": "^7.1.8",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^20.17.31",
+    "@types/node": "^20.19.30",
     "@types/pg-copy-streams": "^1.2.5",
+    "@types/sinon": "^21.0.0",
     "@voxpelli/eslint-config": "^23.0.0",
-    "@voxpelli/tsconfig": "^15.1.2",
+    "@voxpelli/tsconfig": "^16.1.0",
     "c8": "^10.1.3",
     "chai": "^4.5.0",
     "chai-as-promised": "^7.1.2",
-    "dotenv": "^16.5.0",
-    "eslint": "^9.25.1",
+    "dotenv": "^17.2.3",
+    "eslint": "^9.39.2",
     "husky": "^9.1.7",
     "installed-check": "^9.3.0",
-    "knip": "^5.50.5",
-    "mocha": "^11.1.0",
-    "npm-run-all2": "^7.0.2",
+    "knip": "^5.82.1",
+    "mocha": "^11.7.5",
+    "npm-run-all2": "^8.0.4",
+    "sinon": "^21.0.1",
     "type-coverage": "^2.29.7",
-    "typescript": "~5.8.3",
+    "typescript": "~5.9.3",
     "validate-conventional-commit": "^1.0.4"
   },
   "dependencies": {
     "@types/pg": "^8.11.10",
     "pg": "^8.13.1",
-    "pg-copy-streams": "^6.0.6",
+    "pg-copy-streams": "^7.0.0",
     "umzeption": "^0.4.1",
     "umzug": "^3.8.2"
   }