pgsql-test 5.16.1 → 5.17.0

package/README.md

@@ -131,6 +131,7 @@ The `PgTestClient` returned by `getConnections()` wraps a `pg.Client` and provid
 * `beforeEach()` – Begins a transaction and sets a savepoint (called at the start of each test)
 * `afterEach()` – Rolls back to the savepoint and commits the outer transaction (cleans up test state)
 * `setContext({ key: value })` – Sets PostgreSQL config variables (like `role`) to simulate RLS contexts
+* `checkConstraints()` – Runs the commit-time checks for any pending deferred constraints now, without committing (see [Deferred constraints](#deferred-constraints-under-rollback-isolation))
 * `any`, `one`, `oneOrNone`, `many`, `manyOrNone`, `none`, `result` – Typed query helpers for specific result expectations
 
 These methods make it easier to build expressive and isolated integration tests with strong typing and error handling.
@@ -601,6 +602,34 @@ This table documents the available options for the `getConnections` function. Th
 | `db.template`            | `string`   | `undefined`      | Template database used for faster test DB creation                          |
 | `db.rootDb`              | `string`   | `'postgres'`     | Root database used for administrative operations (e.g., creating databases) |
 | `db.prefix`              | `string`   | `'db-'`          | Prefix used when generating test database names                             |
+| `db.deferredConstraints` | `'off' \| 'check' \| 'immediate'` | `'off'` | How `DEFERRABLE INITIALLY DEFERRED` constraints are handled under rollback isolation (env: `DB_DEFERRED_CONSTRAINTS`). See below. |
+
+### Deferred constraints under rollback isolation
+
+`beforeEach()`/`afterEach()` isolate tests by rolling back instead of committing. Anything Postgres only does **at COMMIT** therefore never happens inside a test. The one that bites is `DEFERRABLE INITIALLY DEFERRED` constraints (FK / UNIQUE / EXCLUDE / `CONSTRAINT TRIGGER`): a test can leave a dangling deferred foreign key and still pass, because the check that would have failed the commit is discarded with the rollback. This is inherent to every rollback-based test harness, not specific to pgsql-test.
+
+`db.deferredConstraints` controls what to do about it:
+
+| Mode          | What happens                                                                                                                                                                                              | Trade-off                                                                                                                                                              |
+| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'off'`       | Nothing (default, previous behaviour).                                                                                                                                                                    | Deferred violations pass silently.                                                                                                                                     |
+| `'check'`     | `afterEach()` runs `SET CONSTRAINTS ALL IMMEDIATE` as the last statement before rolling back. Postgres defines this as running exactly the checks COMMIT would have run, so deferral still works *inside* the test and a pending violation fails the test. | The failure surfaces in `afterEach`, not on the offending line (the message names the constraint and table). If the test body already raised a Postgres error, the check is skipped so the original error is not masked. |
+| `'immediate'` | `beforeEach()` runs `SET CONSTRAINTS ALL IMMEDIATE`, so every deferred constraint is checked per statement and a violation fails on the exact line.                                                        | Changes semantics: code that legitimately relies on deferral (insert child before parent, swap two values under a deferred UNIQUE) fails in tests but works in production. |
+
+```ts
+const { db, teardown } = await getConnections({ db: { deferredConstraints: 'check' } });
+```
+
+A test that wants to *assert* that a deferred constraint is enforced can call `checkConstraints()` itself; once it has thrown, the pending events are consumed and `afterEach()` is clean:
+
+```ts
+it('rejects orphan children at commit', async () => {
+  await db.query(`INSERT INTO children (parent_id) VALUES (999)`);
+  await expect(db.checkConstraints()).rejects.toThrow(/children_parent_id_fkey/);
+});
+```
+
+Other commit-only effects — `NOTIFY` delivery and visibility to other sessions — are not covered by any mode; use `publish()` (which really commits) when a test needs them.
 
 ### `pg` Options (PgConfig)
 

package/connect.js

@@ -53,7 +53,9 @@ const getConnections = async (cn = {}, seedAdapters = [seed_1.seed.pgpm()]) => {
     }
     await admin.grantConnect(connOpts.connections.app.user, config.database);
     manager = manager_1.PgTestConnector.getInstance(config);
-    const pg = manager.getClient(config);
+    const pg = manager.getClient(config, {
+        deferredConstraints: connOpts.deferredConstraints
+    });
     let teardownPromise = null;
     let teardownOpts = {};
     const teardown = async (opts = {}) => {
@@ -97,7 +99,8 @@ const getConnections = async (cn = {}, seedAdapters = [seed_1.seed.pgpm()]) => {
     };
     const db = manager.getClient(dbConfig, {
         auth: connOpts.auth,
-        roles: connOpts.roles
+        roles: connOpts.roles,
+        deferredConstraints: connOpts.deferredConstraints
     });
     db.setContext({ role: (0, pgsql_client_1.getDefaultRole)(connOpts) });
     return { pg, db, teardown, manager, admin };

package/esm/connect.js

@@ -49,7 +49,9 @@ export const getConnections = async (cn = {}, seedAdapters = [seed.pgpm()]) => {
     }
     await admin.grantConnect(connOpts.connections.app.user, config.database);
     manager = PgTestConnector.getInstance(config);
-    const pg = manager.getClient(config);
+    const pg = manager.getClient(config, {
+        deferredConstraints: connOpts.deferredConstraints
+    });
     let teardownPromise = null;
     let teardownOpts = {};
     const teardown = async (opts = {}) => {
@@ -93,7 +95,8 @@ export const getConnections = async (cn = {}, seedAdapters = [seed.pgpm()]) => {
     };
     const db = manager.getClient(dbConfig, {
         auth: connOpts.auth,
-        roles: connOpts.roles
+        roles: connOpts.roles,
+        deferredConstraints: connOpts.deferredConstraints
     });
     db.setContext({ role: getDefaultRole(connOpts) });
     return { pg, db, teardown, manager, admin };

package/esm/test-client.js

@@ -4,6 +4,7 @@ import { loadCsvMap } from 'pgsql-seed';
 import { loadSqlFiles } from 'pgsql-seed';
 import { deployPgpm } from 'pgsql-seed';
 import { formatPgError } from './utils';
+const IN_FAILED_SQL_TRANSACTION = '25P02';
 export class PgTestClient extends PgClient {
     testOpts;
     constructor(config, opts = {}) {
@@ -34,13 +35,51 @@ export class PgTestClient extends PgClient {
             throw err;
         }
     }
+    get deferredConstraintsMode() {
+        return this.testOpts.deferredConstraints ?? 'off';
+    }
     async beforeEach() {
         await this.begin();
         await this.savepoint();
+        if (this.deferredConstraintsMode === 'immediate') {
+            await this.setConstraintsImmediate();
+        }
     }
     async afterEach() {
+        let violation;
+        if (this.deferredConstraintsMode === 'check') {
+            try {
+                await this.checkConstraints();
+            }
+            catch (err) {
+                if (err?.code !== IN_FAILED_SQL_TRANSACTION)
+                    violation = err;
+            }
+        }
         await this.rollback();
         await this.commit();
+        if (violation)
+            throw violation;
+    }
+    /**
+     * Run the commit-time checks for every pending deferred constraint now, without committing.
+     * Postgres checks all outstanding deferred constraint events when a constraint switches from
+     * DEFERRED to IMMEDIATE, so this fails exactly where a real COMMIT would have failed.
+     * Once it passes (or throws), the pending events are consumed.
+     */
+    async checkConstraints() {
+        try {
+            await this.setConstraintsImmediate();
+        }
+        catch (err) {
+            if (err?.code !== IN_FAILED_SQL_TRANSACTION) {
+                err.message = `[pgsql-test] deferred constraint violated at end of test (a real COMMIT would have failed here):\n${err.message}`;
+            }
+            throw err;
+        }
+    }
+    async setConstraintsImmediate() {
+        await this.query('SET CONSTRAINTS ALL IMMEDIATE');
     }
     /**
      * Commit current transaction to make data visible to other connections, then start fresh transaction.
@@ -50,6 +89,9 @@ export class PgTestClient extends PgClient {
         await this.commit(); // make data visible to other sessions
         await this.begin(); // fresh tx
         await this.savepoint(); // keep rollback harness
+        if (this.deferredConstraintsMode === 'immediate') {
+            await this.setConstraintsImmediate();
+        }
         await this.ctxQuery(); // reapply all setContext()
     }
     async loadJson(data) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgsql-test",
-  "version": "5.16.1",
+  "version": "5.17.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "pgsql-test offers isolated, role-aware, and rollback-friendly PostgreSQL environments for integration tests — giving developers realistic test coverage without external state pollution",
   "main": "index.js",
@@ -55,21 +55,21 @@
     "test:watch": "jest --watch"
   },
   "devDependencies": {
-    "@pgpmjs/core": "7.32.0",
+    "@pgpmjs/core": "7.32.2",
     "@types/pg": "^8.20.4",
     "@types/pg-copy-streams": "^1.2.5",
     "makage": "^0.8.0"
   },
   "dependencies": {
-    "@pgpmjs/env": "^2.45.1",
+    "@pgpmjs/env": "^2.46.0",
     "@pgpmjs/logger": "^2.26.0",
-    "@pgpmjs/server-utils": "^3.29.1",
-    "@pgpmjs/types": "^2.55.1",
+    "@pgpmjs/server-utils": "^3.29.3",
+    "@pgpmjs/types": "^2.56.0",
     "pg": "^8.21.0",
-    "pg-cache": "^3.29.1",
+    "pg-cache": "^3.29.3",
     "pg-env": "^1.32.0",
-    "pgsql-client": "^4.16.1",
-    "pgsql-seed": "^3.15.1"
+    "pgsql-client": "^4.16.3",
+    "pgsql-seed": "^3.15.3"
   },
-  "gitHead": "0e26550efd7cd782ecaa106be30b3251efd97e6e"
+  "gitHead": "4c68f85c7d9b3c72082f8305dffc0b3dfca80941"
 }

package/test-client.d.ts

@@ -1,3 +1,4 @@
+import { DeferredConstraintsMode } from '@pgpmjs/types';
 import { QueryResult } from 'pg';
 import { PgConfig } from 'pg-env';
 import { PgClient, PgClientOpts } from 'pgsql-client';
@@ -10,6 +11,11 @@ export type PgTestClientOpts = PgClientOpts & {
      * Can be disabled by setting enhancedErrors: false.
      */
     enhancedErrors?: boolean;
+    /**
+     * How DEFERRABLE INITIALLY DEFERRED constraints are handled under rollback isolation.
+     * Defaults to 'off'. See {@link DeferredConstraintsMode}.
+     */
+    deferredConstraints?: DeferredConstraintsMode;
 };
 export declare class PgTestClient extends PgClient {
     protected testOpts: PgTestClientOpts;
@@ -24,8 +30,17 @@ export declare class PgTestClient extends PgClient {
      * When enhancedErrors is enabled, errors will include detail, hint, where, position, etc.
      */
     query<T = any>(query: string, values?: any[]): Promise<QueryResult<T>>;
+    private get deferredConstraintsMode();
     beforeEach(): Promise<void>;
     afterEach(): Promise<void>;
+    /**
+     * Run the commit-time checks for every pending deferred constraint now, without committing.
+     * Postgres checks all outstanding deferred constraint events when a constraint switches from
+     * DEFERRED to IMMEDIATE, so this fails exactly where a real COMMIT would have failed.
+     * Once it passes (or throws), the pending events are consumed.
+     */
+    checkConstraints(): Promise<void>;
+    private setConstraintsImmediate;
     /**
      * Commit current transaction to make data visible to other connections, then start fresh transaction.
      * Maintains test isolation by creating a savepoint and reapplying session context.

package/test-client.js

@@ -7,6 +7,7 @@ const pgsql_seed_2 = require("pgsql-seed");
 const pgsql_seed_3 = require("pgsql-seed");
 const pgsql_seed_4 = require("pgsql-seed");
 const utils_1 = require("./utils");
+const IN_FAILED_SQL_TRANSACTION = '25P02';
 class PgTestClient extends pgsql_client_1.PgClient {
     testOpts;
     constructor(config, opts = {}) {
@@ -37,13 +38,51 @@ class PgTestClient extends pgsql_client_1.PgClient {
             throw err;
         }
     }
+    get deferredConstraintsMode() {
+        return this.testOpts.deferredConstraints ?? 'off';
+    }
     async beforeEach() {
         await this.begin();
         await this.savepoint();
+        if (this.deferredConstraintsMode === 'immediate') {
+            await this.setConstraintsImmediate();
+        }
     }
     async afterEach() {
+        let violation;
+        if (this.deferredConstraintsMode === 'check') {
+            try {
+                await this.checkConstraints();
+            }
+            catch (err) {
+                if (err?.code !== IN_FAILED_SQL_TRANSACTION)
+                    violation = err;
+            }
+        }
         await this.rollback();
         await this.commit();
+        if (violation)
+            throw violation;
+    }
+    /**
+     * Run the commit-time checks for every pending deferred constraint now, without committing.
+     * Postgres checks all outstanding deferred constraint events when a constraint switches from
+     * DEFERRED to IMMEDIATE, so this fails exactly where a real COMMIT would have failed.
+     * Once it passes (or throws), the pending events are consumed.
+     */
+    async checkConstraints() {
+        try {
+            await this.setConstraintsImmediate();
+        }
+        catch (err) {
+            if (err?.code !== IN_FAILED_SQL_TRANSACTION) {
+                err.message = `[pgsql-test] deferred constraint violated at end of test (a real COMMIT would have failed here):\n${err.message}`;
+            }
+            throw err;
+        }
+    }
+    async setConstraintsImmediate() {
+        await this.query('SET CONSTRAINTS ALL IMMEDIATE');
     }
     /**
      * Commit current transaction to make data visible to other connections, then start fresh transaction.
@@ -53,6 +92,9 @@ class PgTestClient extends pgsql_client_1.PgClient {
         await this.commit(); // make data visible to other sessions
         await this.begin(); // fresh tx
         await this.savepoint(); // keep rollback harness
+        if (this.deferredConstraintsMode === 'immediate') {
+            await this.setConstraintsImmediate();
+        }
         await this.ctxQuery(); // reapply all setContext()
     }
     async loadJson(data) {