@voxpelli/pg-utils 2.3.1 → 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;IA0Eb,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;;sBA3Ia,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;
@@ -104,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();
@@ -128,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);
     }
@@ -149,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.1",
+  "version": "3.0.0",
   "description": " My personal database utils / helpers for Postgres",
   "homepage": "http://github.com/voxpelli/pg-utils",
   "repository": {