pgsql-test 2.18.4 → 2.18.5

package/esm/stream.js

@@ -22,22 +22,75 @@ function stringToStream(text) {
     });
     return stream;
 }
+/**
+ * Executes SQL statements by streaming them to psql.
+ *
+ * IMPORTANT: PostgreSQL stderr handling
+ * -------------------------------------
+ * PostgreSQL sends different message types to stderr, not just errors:
+ *   - ERROR: Actual SQL errors (should fail)
+ *   - WARNING: Potential issues (informational)
+ *   - NOTICE: Informational messages (should NOT fail)
+ *   - INFO: Informational messages (should NOT fail)
+ *   - DEBUG: Debug messages (should NOT fail)
+ *
+ * Example scenario that previously caused false failures:
+ * When running SQL like:
+ *   GRANT administrator TO app_user;
+ *
+ * If app_user is already a member of administrator, PostgreSQL outputs:
+ *   NOTICE: role "app_user" is already a member of role "administrator"
+ *
+ * This is NOT an error - the GRANT succeeded (it's idempotent). But because
+ * this message goes to stderr, the old implementation would reject the promise
+ * and fail the test, even though nothing was wrong.
+ *
+ * Solution:
+ * 1. Buffer stderr instead of rejecting immediately on any output
+ * 2. Use ON_ERROR_STOP=1 so psql exits with non-zero code on actual SQL errors
+ * 3. Only reject if the exit code is non-zero, using buffered stderr as the error message
+ *
+ * This way, NOTICE/WARNING messages are collected but don't cause failures,
+ * while actual SQL errors still properly fail with meaningful error messages.
+ */
 export async function streamSql(config, sql) {
-    const args = setArgs(config);
+    const args = [
+        ...setArgs(config),
+        // ON_ERROR_STOP=1 makes psql exit with a non-zero code when it encounters
+        // an actual SQL error. Without this, psql might continue executing subsequent
+        // statements and exit with code 0 even if some statements failed.
+        '-v', 'ON_ERROR_STOP=1'
+    ];
     return new Promise((resolve, reject) => {
         const sqlStream = stringToStream(sql);
+        // Buffer stderr instead of rejecting immediately. This allows us to collect
+        // all output (including harmless NOTICE messages) and only use it for error
+        // reporting if the process actually fails.
+        let stderrBuffer = '';
         const proc = spawn('psql', args, {
             env: getSpawnEnvWithPg(config)
         });
         sqlStream.pipe(proc.stdin);
+        // Collect stderr output. We don't reject here because stderr may contain
+        // harmless NOTICE/WARNING messages that shouldn't cause test failures.
+        proc.stderr.on('data', (data) => {
+            stderrBuffer += data.toString();
+        });
+        // Determine success/failure based on exit code, not stderr content.
+        // Exit code 0 = success (even if there were NOTICE messages on stderr)
+        // Exit code non-zero = actual error occurred
         proc.on('close', (code) => {
-            resolve();
+            if (code !== 0) {
+                // Include the buffered stderr in the error message for debugging
+                reject(new Error(stderrBuffer || `psql exited with code ${code}`));
+            }
+            else {
+                resolve();
+            }
         });
+        // Handle spawn errors (e.g., psql not found)
         proc.on('error', (error) => {
             reject(error);
         });
-        proc.stderr.on('data', (data) => {
-            reject(new Error(data.toString()));
-        });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgsql-test",
-  "version": "2.18.4",
+  "version": "2.18.5",
   "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",
@@ -71,5 +71,5 @@
     "pg-copy-streams": "^7.0.0",
     "pg-env": "^1.2.4"
   },
-  "gitHead": "fc182ff9e4c4745a3e86eda6d58e3b0061f36564"
+  "gitHead": "c61d285656df312ee59fdf2659e63cbaadff2370"
 }

package/stream.d.ts

@@ -1,2 +1,33 @@
 import { PgConfig } from 'pg-env';
+/**
+ * Executes SQL statements by streaming them to psql.
+ *
+ * IMPORTANT: PostgreSQL stderr handling
+ * -------------------------------------
+ * PostgreSQL sends different message types to stderr, not just errors:
+ *   - ERROR: Actual SQL errors (should fail)
+ *   - WARNING: Potential issues (informational)
+ *   - NOTICE: Informational messages (should NOT fail)
+ *   - INFO: Informational messages (should NOT fail)
+ *   - DEBUG: Debug messages (should NOT fail)
+ *
+ * Example scenario that previously caused false failures:
+ * When running SQL like:
+ *   GRANT administrator TO app_user;
+ *
+ * If app_user is already a member of administrator, PostgreSQL outputs:
+ *   NOTICE: role "app_user" is already a member of role "administrator"
+ *
+ * This is NOT an error - the GRANT succeeded (it's idempotent). But because
+ * this message goes to stderr, the old implementation would reject the promise
+ * and fail the test, even though nothing was wrong.
+ *
+ * Solution:
+ * 1. Buffer stderr instead of rejecting immediately on any output
+ * 2. Use ON_ERROR_STOP=1 so psql exits with non-zero code on actual SQL errors
+ * 3. Only reject if the exit code is non-zero, using buffered stderr as the error message
+ *
+ * This way, NOTICE/WARNING messages are collected but don't cause failures,
+ * while actual SQL errors still properly fail with meaningful error messages.
+ */
 export declare function streamSql(config: PgConfig, sql: string): Promise<void>;

package/stream.js

@@ -25,22 +25,75 @@ function stringToStream(text) {
     });
     return stream;
 }
+/**
+ * Executes SQL statements by streaming them to psql.
+ *
+ * IMPORTANT: PostgreSQL stderr handling
+ * -------------------------------------
+ * PostgreSQL sends different message types to stderr, not just errors:
+ *   - ERROR: Actual SQL errors (should fail)
+ *   - WARNING: Potential issues (informational)
+ *   - NOTICE: Informational messages (should NOT fail)
+ *   - INFO: Informational messages (should NOT fail)
+ *   - DEBUG: Debug messages (should NOT fail)
+ *
+ * Example scenario that previously caused false failures:
+ * When running SQL like:
+ *   GRANT administrator TO app_user;
+ *
+ * If app_user is already a member of administrator, PostgreSQL outputs:
+ *   NOTICE: role "app_user" is already a member of role "administrator"
+ *
+ * This is NOT an error - the GRANT succeeded (it's idempotent). But because
+ * this message goes to stderr, the old implementation would reject the promise
+ * and fail the test, even though nothing was wrong.
+ *
+ * Solution:
+ * 1. Buffer stderr instead of rejecting immediately on any output
+ * 2. Use ON_ERROR_STOP=1 so psql exits with non-zero code on actual SQL errors
+ * 3. Only reject if the exit code is non-zero, using buffered stderr as the error message
+ *
+ * This way, NOTICE/WARNING messages are collected but don't cause failures,
+ * while actual SQL errors still properly fail with meaningful error messages.
+ */
 async function streamSql(config, sql) {
-    const args = setArgs(config);
+    const args = [
+        ...setArgs(config),
+        // ON_ERROR_STOP=1 makes psql exit with a non-zero code when it encounters
+        // an actual SQL error. Without this, psql might continue executing subsequent
+        // statements and exit with code 0 even if some statements failed.
+        '-v', 'ON_ERROR_STOP=1'
+    ];
     return new Promise((resolve, reject) => {
         const sqlStream = stringToStream(sql);
+        // Buffer stderr instead of rejecting immediately. This allows us to collect
+        // all output (including harmless NOTICE messages) and only use it for error
+        // reporting if the process actually fails.
+        let stderrBuffer = '';
         const proc = (0, child_process_1.spawn)('psql', args, {
             env: (0, pg_env_1.getSpawnEnvWithPg)(config)
         });
         sqlStream.pipe(proc.stdin);
+        // Collect stderr output. We don't reject here because stderr may contain
+        // harmless NOTICE/WARNING messages that shouldn't cause test failures.
+        proc.stderr.on('data', (data) => {
+            stderrBuffer += data.toString();
+        });
+        // Determine success/failure based on exit code, not stderr content.
+        // Exit code 0 = success (even if there were NOTICE messages on stderr)
+        // Exit code non-zero = actual error occurred
         proc.on('close', (code) => {
-            resolve();
+            if (code !== 0) {
+                // Include the buffered stderr in the error message for debugging
+                reject(new Error(stderrBuffer || `psql exited with code ${code}`));
+            }
+            else {
+                resolve();
+            }
         });
+        // Handle spawn errors (e.g., psql not found)
         proc.on('error', (error) => {
             reject(error);
         });
-        proc.stderr.on('data', (data) => {
-            reject(new Error(data.toString()));
-        });
     });
 }