{"id":17327,"library":"pg-mermaid","title":"PostgreSQL to Mermaid ERD Generator","description":"pg-mermaid is an open-source command-line interface (CLI) tool designed to generate Entity-Relationship Diagram (ERD) definitions in Mermaid syntax directly from a PostgreSQL database schema. Currently at version 0.2.1, it is explicitly marked as experimental and a work in progress, indicating an early stage of development with potential for frequent, unannounced changes and incomplete features. Its primary function is to simplify the visualization of database structures for documentation and communication, leveraging the human-readable Mermaid markdown language. Unlike general-purpose schema introspection tools, pg-mermaid focuses specifically on PostgreSQL and outputs a format readily renderable by Mermaid-compatible viewers and platforms. Given its early version, a stable release cadence is not yet established, and users should anticipate ongoing development rather than fixed schedules.","status":"active","version":"0.2.1","language":"javascript","source_language":"en","source_url":"https://github.com/bastiensun/pg-mermaid","tags":["javascript","diagram","entity relationship diagram","er diagram","mermaid","postgres","postgresql","typescript"],"install":[{"cmd":"npm install pg-mermaid","lang":"bash","label":"npm"},{"cmd":"yarn add pg-mermaid","lang":"bash","label":"yarn"},{"cmd":"pnpm add pg-mermaid","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency, common for TypeScript projects at runtime.","package":"tslib","optional":false}],"imports":[],"quickstart":{"code":"PGPASSWORD=\"your_strong_password\" npx pg-mermaid \\\n  --dbname mydatabase \\\n  --username myuser \\\n  --host localhost \\\n  --port 5432 \\\n  --schema public \\\n  --output-path ./mydatabase-erd.md \\\n  --excluded-tables audit_logs,temp_data \\\n  && echo \"Mermaid ERD generated to mydatabase-erd.md\"","lang":"bash","description":"Generates a Mermaid ERD markdown file for a PostgreSQL database, excluding specified tables."},"warnings":[{"fix":"Monitor GitHub releases for changes. Consider pinning to exact versions in production environments or using a version range with caution.","message":"The package is explicitly marked as 'experimental' and 'work in progress'. Users should anticipate frequent breaking changes, incomplete features, and potential instability across minor versions (e.g., between 0.2.x and 0.3.x) as the API and functionality are not yet finalized.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"Use a robust secrets management system. Avoid hardcoding passwords. Ensure shell history is not saving sensitive commands. For automated scripts, consider temporary environment variable settings or specific CI/CD secret handling.","message":"Sensitive database credentials (PGPASSWORD) are passed via environment variables. While this is a common practice, ensure your environment is secure and that credentials are not exposed in command history or process listings, especially in shared or compromised systems.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Install `pg-mermaid` globally (`npm install -g pg-mermaid`) or locally (`npm install pg-mermaid`) and then use `pg-mermaid ...` or `npx pg-mermaid ...` respectively to avoid repeated downloads and ensure a specific version.","message":"The tool uses `npx`, which downloads the package on-demand if not already cached. This can lead to slower execution times on first use or without a stable internet connection, and might introduce security risks if the npm registry is compromised.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Review the generated Mermaid Markdown carefully for any missing or incorrectly represented schema elements. Manual adjustments to the Markdown output may be necessary for complex database designs. Provide feedback to the project maintainers for feature requests.","message":"The current version primarily supports basic table and column relationships. Advanced PostgreSQL features like complex constraints, stored procedures, views, or custom data types might not be fully represented or accurately translated into Mermaid ERD syntax.","severity":"gotcha","affected_versions":"<1.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure your PostgreSQL server is running. Verify the `--host` and `--port` options are correct. Check firewall rules and network connectivity between where `pg-mermaid` is run and the database server.","cause":"The PostgreSQL database server is not running, is not accessible from the host, or is listening on a different port/address than specified.","error":"Error: connect ECONNREFUSED 127.0.0.1:5432"},{"fix":"Double-check the `--username` parameter and the `PGPASSWORD` environment variable. Ensure the user exists and has the correct password set in PostgreSQL. Also check if the user has permissions to connect from the specified host.","cause":"Incorrect username or password provided for the PostgreSQL connection. The user might not exist, or the password is wrong.","error":"FATAL: password authentication failed for user \"myuser\""},{"fix":"Verify the `--dbname` parameter matches an existing database on your PostgreSQL instance. Check for typos or case sensitivity in the database name.","cause":"The specified database name `--dbname` does not exist on the connected PostgreSQL server instance.","error":"Error: Database 'mydatabase' does not exist"}],"ecosystem":"npm","meta_description":null}