{"id":14809,"library":"pg-test","title":"PostgreSQL SQL Test Runner","description":"pg-test is a focused command-line interface (CLI) utility designed for running tests directly from `.sql` files against a PostgreSQL database. As of version 1.0.7, it provides a straightforward mechanism for database-centric testing, executing each `.sql` file in a specified directory sequentially and stopping on the first failure. Its release cadence appears to be stable and utility-focused, without frequent major updates. Key differentiators include its simplicity, direct execution of SQL scripts, and reliance on a `DB` environment variable for database connection, making it suitable for CI environments like Travis-CI. Unlike typical JavaScript test runners, pg-test primarily operates on raw SQL files rather than integrating with JS/TS test frameworks.","status":"active","version":"1.0.7","language":"javascript","source_language":"en","source_url":"https://github.com/abrkn/pg-test","tags":["javascript"],"install":[{"cmd":"npm install pg-test","lang":"bash","label":"npm"},{"cmd":"yarn add pg-test","lang":"bash","label":"yarn"},{"cmd":"pnpm add pg-test","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"pg-test is primarily a CLI tool. There are no documented direct programmatic exports for `import { ... } from 'pg-test'`. To execute it from a Node.js script, use `child_process` methods. Do not attempt to import symbols as if it were a library.","wrong":"import { run } from 'pg-test';","symbol":"pg-test","correct":"import { spawn } from 'child_process'; spawn('pg-test', ['path/to/tests'], { stdio: 'inherit' });"},{"note":"This package is a CLI application. It does not export a `PgTestRunner` class or similar for programmatic instantiation. Its functionality is accessed via the command line.","wrong":"import PgTestRunner from 'pg-test';","symbol":"PgTestRunner","correct":"// No direct programmatic API documented for import."},{"note":"Configuration for pg-test is handled through the `DB` environment variable for database connection and CLI arguments for the test path. There is no `configure` function or similar API to import.","wrong":"import { configure } from 'pg-test';","symbol":"Configuration","correct":"// Configuration is via environment variables or CLI arguments."}],"quickstart":{"code":"import { spawnSync } from 'child_process';\nimport path from 'path';\nimport fs from 'fs';\n\n// Create a dummy test file\nconst testFilePath = path.join(process.cwd(), 'temp_test.sql');\nfs.writeFileSync(testFilePath, 'SELECT 1 = 1; -- Should pass');\n\n// Set the DB environment variable (replace with your actual DB URL)\n// For local PostgreSQL without password: 'postgres://postgres@localhost/your_db_name'\n// Make sure 'your_db_name' exists and is accessible.\nprocess.env.DB = process.env.DB ?? 'postgres://postgres@localhost/testdb';\n\nconsole.log(`Running pg-test against: ${process.env.DB}`);\n\nconst result = spawnSync('pg-test', [path.dirname(testFilePath)], {\n  stdio: 'inherit',\n  env: process.env\n});\n\nif (result.status !== 0) {\n  console.error('pg-test failed!');\n} else {\n  console.log('pg-test completed successfully.');\n}\n\n// Clean up the dummy test file\nfs.unlinkSync(testFilePath);","lang":"typescript","description":"Demonstrates how to run `pg-test` programmatically using `child_process` after setting the required `DB` environment variable, including creating a temporary SQL test file."},"warnings":[{"fix":"Ensure `export DB=postgres://user:password@host:port/database` (Linux/macOS) or `$env:DB='...'` (Windows PowerShell) is run before `pg-test`.","message":"The `DB` environment variable is mandatory for `pg-test` to connect to PostgreSQL. If not set, the tool will likely fail with a connection error or use an unexpected default (like `travis` on Travis-CI).","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Interact with `pg-test` via `child_process.spawn` or `exec` methods in Node.js, or by running the `pg-test` command directly in your shell or CI/CD pipeline.","message":"pg-test is a CLI-first tool. There is no documented or intended programmatic API for `import`ing functions or classes directly from the package. Attempting to do so will result in import errors or undefined behavior.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Consider structuring tests into smaller, independent files or using other test runners if comprehensive failure reporting is required.","message":"The runner stops on the first SQL file failure. This means it's not designed to report all failures in a suite but rather to immediately halt execution, which can be less informative for large test suites.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use pg-test for simple, direct SQL validation. For more complex testing scenarios involving application logic, integrate with a JS/TS test runner and a PostgreSQL client library (e.g., `node-postgres`).","message":"pg-test executes raw SQL files. This limits its capabilities compared to full-fledged JavaScript/TypeScript test frameworks (e.g., dynamic test generation, complex assertions, mocking).","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Set the `DB` environment variable with a valid PostgreSQL connection string before running `pg-test`. Example: `export DB=postgres://user:pass@host:port/dbname`.","cause":"The required PostgreSQL connection URL was not provided via the `DB` environment variable.","error":"Error: Environment variable DB is not set"},{"fix":"Verify that your PostgreSQL server is running, the specified host and port in the `DB` environment variable are correct, and no firewall is blocking the connection. Check PostgreSQL logs for details.","cause":"The `pg-test` utility could not establish a connection to the PostgreSQL server, likely due to the server not running, incorrect host/port, or firewall issues.","error":"Error: connect ECONNREFUSED 127.0.0.1:5432"},{"fix":"Review the SQL file where the error occurred. Correct the syntax. The error message usually provides clues about the line number or near where the error happened.","cause":"One of your `.sql` test files contains invalid SQL syntax.","error":"syntax error at or near \"SELECT\""}],"ecosystem":"npm"}