PostgreSQL to Mermaid ERD Generator

0.2.1 · active · verified Wed Apr 22

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.

Common errors

```
Error: connect ECONNREFUSED 127.0.0.1:5432
```
cause The PostgreSQL database server is not running, is not accessible from the host, or is listening on a different port/address than specified.

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.
```
FATAL: password authentication failed for user "myuser"
```
cause Incorrect username or password provided for the PostgreSQL connection. The user might not exist, or the password is wrong.

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.
```
Error: Database 'mydatabase' does not exist
```
cause The specified database name `--dbname` does not exist on the connected PostgreSQL server instance.

fix Verify the `--dbname` parameter matches an existing database on your PostgreSQL instance. Check for typos or case sensitivity in the database name.

Warnings

breaking 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.
Fix: Monitor GitHub releases for changes. Consider pinning to exact versions in production environments or using a version range with caution.
gotcha 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.
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.
gotcha 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.
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.
gotcha 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.
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.

Install

npm install pg-mermaid npm
yarn add pg-mermaid yarn
pnpm add pg-mermaid pnpm

Quickstart

Generates a Mermaid ERD markdown file for a PostgreSQL database, excluding specified tables.

PGPASSWORD="your_strong_password" npx pg-mermaid \
  --dbname mydatabase \
  --username myuser \
  --host localhost \
  --port 5432 \
  --schema public \
  --output-path ./mydatabase-erd.md \
  --excluded-tables audit_logs,temp_data \
  && echo "Mermaid ERD generated to mydatabase-erd.md"

view raw JSON →