{"id":14518,"library":"cypress-postgresql","title":"Cypress PostgreSQL Database Integration","description":"This package provides a set of Cypress commands and plugin utilities for interacting directly with a PostgreSQL database during end-to-end tests. It allows test suites to execute SQL queries, verify data, or seed test data by leveraging the `pg` client library. The current stable version is 1.0.8. Based on the README, it appears to support older Cypress plugin architectures (e.g., `cypress/plugins/index.js`), which suggests it is not actively maintained for the latest Cypress versions (Cypress 10+ uses `cypress.config.js`). Its primary differentiation is enabling direct database interaction within Cypress tests, streamlining data setup and verification workflows, offering a direct bridge for database operations within the Cypress testing environment, which can be critical for test data management and assertions.","status":"abandoned","version":"1.0.8","language":"javascript","source_language":"en","source_url":"https://github.com/hovigstep/cypress-postgresql","tags":["javascript","postgresql","cypress","db","server"],"install":[{"cmd":"npm install cypress-postgresql","lang":"bash","label":"npm"},{"cmd":"yarn add cypress-postgresql","lang":"bash","label":"yarn"},{"cmd":"pnpm add cypress-postgresql","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required as a peer dependency for database connection pooling and query execution within the Cypress plugin file.","package":"pg","optional":false}],"imports":[{"note":"Used for loading Cypress custom commands. The package exports its main functionality as a default export.","wrong":"import { postgreSQL } from 'cypress-postgresql';","symbol":"postgreSQL","correct":"import postgreSQL from 'cypress-postgresql';"},{"note":"This function is exposed as a method on the default export for CommonJS environments (e.g., `cypress/plugins/index.js`).","wrong":"import { loadDBPlugin } from 'cypress-postgresql';","symbol":"loadDBPlugin","correct":"const postgreSQL = require('cypress-postgresql');\n// then tasks = postgreSQL.loadDBPlugin(pool);"},{"note":"This function is exposed as a method on the default export for ES module environments (e.g., `cypress/support/index.js`).","wrong":"import { loadDBCommands } from 'cypress-postgresql';","symbol":"loadDBCommands","correct":"import postgreSQL from 'cypress-postgresql';\npostgreSQL.loadDBCommands();"}],"quickstart":{"code":"/* cypress.json or cypress.config.js equivalent */\n{\n  \"db\": {\n    \"user\": \"process.env.PG_USER ?? ''\",\n    \"password\": \"process.env.PG_PASSWORD ?? ''\",\n    \"host\": \"localhost\",\n    \"port\": 5432,\n    \"database\": \"test_db\"\n  }\n}\n\n/* cypress/plugins/index.js (Cypress < 10) or cypress.config.js setup */\nconst postgreSQL = require('cypress-postgresql');\nconst { Pool } = require('pg');\nconst dbConfig = require('../../cypress.json'); // Adjust path as needed\n\nmodule.exports = (on, config) => {\n  const pool = new Pool(dbConfig.db);\n  const tasks = postgreSQL.loadDBPlugin(pool);\n  on('task', tasks);\n  return config;\n};\n\n/* cypress/support/commands.js */\nimport postgreSQL from 'cypress-postgresql';\npostgreSQL.loadDBCommands();\n\n/* cypress/e2e/db.cy.js */\ndescribe('Database interactions', () => {\n  beforeEach(() => {\n    // Ensure the database is clean or seeded before each test\n    cy.postgresql('TRUNCATE TABLE users RESTART IDENTITY;').then(() => {\n      cy.log('Users table truncated.');\n    });\n  });\n\n  it('should insert and retrieve data from PostgreSQL', () => {\n    cy.postgresql(`INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com');`)\n      .then(() => {\n        return cy.postgresql(`SELECT name FROM users WHERE email = 'john@example.com';`);\n      })\n      .then((result) => {\n        expect(result[0].name).to.eq('John Doe');\n      });\n  });\n});","lang":"javascript","description":"This quickstart demonstrates how to configure `cypress-postgresql` in a Cypress setup (pre-Cypress 10.0), define database credentials, load custom commands, and execute a basic insert and select query within a test."},"warnings":[{"fix":"For Cypress 10+, manual refactoring is needed to adapt the plugin logic to the `cypress.config.js` setup. This may involve using `defineConfig` and handling `on('task', ...)` directly within the configuration file or creating a custom `setupNodeEvents` function. Alternatively, consider using a more modern Cypress database plugin.","message":"This package relies on the deprecated `cypress/plugins/index.js` file for configuration. It is not compatible with Cypress 10.0+ out-of-the-box, which introduced `cypress.config.js` and a new configuration API. Migration requires significant manual effort.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Ensure `npm install pg` or `yarn add pg` is run in your project's root directory alongside `cypress-postgresql`.","message":"The `pg` (node-postgres) package is a direct dependency for the database connection and must be installed separately by the user. It is not bundled or listed as a peer dependency in the provided metadata.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Utilize environment variables (e.g., `process.env.PG_USER`) in your `cypress.json` or `cypress.config.js` for database credentials. Pass them during test execution, for example, using a `.env` file and a package like `dotenv` or directly in your CI/CD pipeline.","message":"Storing database credentials directly in `cypress.json` (as suggested by the README) is a security risk, especially if the file is committed to version control. Sensitive information should be handled securely.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For new projects, prefer Cypress 10+ and integrate database tasks directly into `cypress.config.js` or explore alternative, actively maintained Cypress database plugins that support the latest configuration patterns.","message":"The package's primary integration method through `cypress/plugins/index.js` is considered a legacy approach in modern Cypress versions. While commands in `cypress/support/index.js` remain viable, the plugin side is outdated.","severity":"deprecated","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":"Ensure `pg` is installed (`npm install pg`) and that `cypress-postgresql` is `require`d in the plugin file (e.g., `const postgreSQL = require('cypress-postgresql');`) as it exposes `loadDBPlugin` as a method on its default export.","cause":"The `cypress-postgresql` module was imported incorrectly, or the `pg` dependency is missing.","error":"TypeError: postgreSQL.loadDBPlugin is not a function"},{"fix":"Verify that your PostgreSQL server is running and accessible from where Cypress tests are executed. Double-check all database credentials in your `cypress.json` file for accuracy. Ensure no firewall rules are blocking the connection.","cause":"The PostgreSQL server is not running, or the database connection details in `cypress.json` (host, port, user, password, database) are incorrect or inaccessible from the Cypress test environment.","error":"Cypress encountered an error while connecting to the database. (connection refused)"},{"fix":"Review your SQL query for typos in table or column names. Confirm that the table and columns exist in the target database. Check the database user's permissions to ensure they have read/write access to the necessary tables.","cause":"The SQL query being executed refers to a table or column that does not exist in the connected PostgreSQL database, or the database user lacks permissions to access it.","error":"error: relation \"your_table_name\" does not exist"}],"ecosystem":"npm"}