pg-mermaid

library0.2.1jsnpmunverified

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.

database data devops

npm install pg-mermaid

github ↗package ↗

INSTALL

IMPORT

SIG · PG-MERMAID

pg-mermaid

databasejavascriptv0.2.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

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"

pg-mermaid --version

Debug

Known issues

breakingThe 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.

affects: >=0.1.0

gotchaSensitive 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.

affects: >=0.1.0

gotchaThe 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.

affects: >=0.1.0

gotchaThe 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.

affects: <1.0.0

Errors

Common errors & fixes

Error: connect ECONNREFUSED 127.0.0.1:5432

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"

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

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.

Upgrade

Version history

0.2.1latest on npm

Audit

Dependencies

tslibrequiredPeer dependency, common for TypeScript projects at runtime.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/bastiensun/pg-mermaid ↗

packagehttps://www.npmjs.com/package/pg-mermaid ↗