mermerd

repository·master·Indexed 20 days ago

A CLI tool that generates Mermaid-JS Entity Relationship Diagrams (ERD) from existing database schemas. It supports PostgreSQL, MySQL, MSSQL, and SQLite3, allowing developers to automate documentation by extracting tables, constraints, and metadata. Features include granular selection of schemas and tables, support for primary and foreign keys, and the ability to output plain Mermaid syntax or Markdown-ready backticks via an interactive CLI or YAML run configurations for CI/CD pipelines.

Tokens: 3.1K
Snippets: 8
Records: 11
Agent score: 69%

What's inside mermerd

Overview of mermerd features
master
Mermerd is a tool that creates Mermaid-JS Entity Relationship Diagrams (ERD) from existing database tables.
Key capabilities:
- Database Support: PostgreSQL, MySQL, MSSQL, and SQLite3.
- Granular Selection: Choose specific schemas and tables to include in the diagram.
- Constraint Visibility: Show primary keys (PK), foreign keys (FK), unique constraints (UK), and NOT NULL constraints.
- Metadata Support: Display enum values, column comments, and NOT NULL constraints in the description column.
- Output Formats: Generate plain Mermaid syntax or output enclosed in Mermaid backticks for direct use in Markdown (e.g., GitHub).
- Interactive CLI: Features multiselect and search for tables and schemas.
https://github.com/karnerth/mermerd/blob/master/readme.md

Use a run configuration for CI/CD pipelines

master

For automated environments like CI/CD, you can bypass interactive prompts by providing a YAML run configuration file via the --runConfig flag. This file specifies all necessary connection and selection parameters.

Example yourRunConfig.yaml:

# Connection properties
connectionString: "postgresql://user:password@localhost:5432/yourDb"

# Define what schemas should be used
useAllSchemas: true
# or
schema: 
  - "public"
  - "other_db"

# Define what tables should be used
useAllTables: true
# or
selectedTables:
  - city
  - customer

# Additional flags
showAllConstraints: true
encloseWithMermaidBackticks: true
outputFileName: "my-db.mmd"
outputMode: stdout
debug: true
omitConstraintLabels: true
omitAttributeKeys: true
showDescriptions:
  - enumValues
  - columnComments
  - notNull
showSchemaPrefix: true
schemaPrefixSeparator: "_"
ignoreTables:
  - city

# Names must match the pattern <schema><schema_prefix><table>
relationshipLabels:
  - "public_table public_another-table : label"

Run it using:

mermerd --runConfig yourRunConfig.yaml

mermerd --runConfig yourRunConfig.yaml

Install mermerd via Go or Releases
master
You can install mermerd using the Go toolchain (requires Go version >= 1.21) or by downloading a pre-compiled executable from the GitHub Releases page. If using the executable, add it to your system PATH to use it globally.
Using Go
To install the latest version:
```
go install github.com/KarnerTh/mermerd@latest
```
To install a specific version:
```
go install github.com/KarnerTh/mermerd@v0.12.0
```
```
go install github.com/KarnerTh/mermerd@latest
```
https://github.com/karnerth/mermerd

Configure mermerd with a global configuration file

master

You can define default settings in a YAML configuration file located at ~/.mermerd in your home directory. This is useful for setting default output names, enabling specific constraint views, or providing connection string suggestions for the interactive CLI (accessible via Tab).

Example ~/.mermerd content:

showAllConstraints: true
encloseWithMermaidBackticks: true
outputFileName: "my-db.mmd"
debug: false
omitConstraintLabels: false
omitAttributeKeys: false
showDescriptions: "enumValues"
showSchemaPrefix: true
schemaPrefixSeparator: "_"

# These connection strings are available as suggestions in the cli (use tab to access)
connectionStringSuggestions:
  - postgresql://user:password@localhost:5432/yourDb
  - mysql://root:password@tcp(127.0.0.1:3306)/yourDb
  - sqlserver://user:password@localhost:1433?database=yourDb
  - sqlite3://mermerd_test.db

showAllConstraints: true
encloseWithMermaidBackticks: true
outputFileName: "my-db.mmd"
debug: false
omitConstraintLabels: false
omitAttributeKeys: false
showDescriptions: "enumValues"
showSchemaPrefix: true
schemaPrefixSeparator: "_"

connectionStringSuggestions:
  - postgresql://user:password@localhost:5432/yourDb
  - mysql://root:password@tcp(127.0.0.1:3306)/yourDb
  - sqlserver://user:password@localhost:1433?database=yourDb
  - sqlite3://mermerd_test.db

Use mermerd CLI to create Mermaid ERD diagrams
master
The mermerd command-line tool analyzes existing database tables and generates Mermaid ERD (Entity Relationship Diagram) syntax. It supports various database connection strings, schema selection, and output modes (either to a file or stdout).
```
# Example: Generate a diagram for a specific schema and output to a file
mermerd -c "your-connection-string" -s "my_schema" -o "my_diagram.mmd"
```
https://github.com/karnerth/mermerd/blob/master/cmd/root.go
Configure mermerd using a configuration file
master
mermerd looks for a configuration file to set global settings.
1. Default Location: It searches for a .mermerd.yaml file in your home directory.
2. Custom Configuration: You can specify a custom configuration file path using the --runConfig flag.
Environment variables used in the configuration file are automatically expanded.
```
# Use a specific configuration file
mermerd --runConfig /path/to/my/config.yaml
```
https://github.com/karnerth/mermerd/blob/master/cmd/root.go

Handle special characters in connection strings

master

When using connection strings with passwords containing special characters, you may encounter a net/url: invalid userinfo error. To resolve this, use percent-encoding for the special characters.

Invalid	Valid
`postgresql://user:password$@localhost:5432/yourDb`	`postgresql://user:password%24@localhost:5432/yourDb`
`postgresql://user:pass[];$/word@localhost:1433?database=yourDb`	`postgresql://user:pass%5B%5D%3B%24%2Fword@localhost:1433?database=yourDb`

Example mermerd CLI commands

master

Common ways to invoke mermerd:

Interactive mode (all parameters via CLI):

mermerd

Show all constraints (even for unselected tables):

mermerd --showAllConstraints

Using a run configuration:

mermerd --runConfig yourRunConfig.yaml

Specify connection and schema to minimize interaction:

mermerd -c "postgresql://user:password@localhost:5432/yourDb" -s public

Use all tables in a schema without interaction:

mermerd -c "postgresql://user:password@localhost:5432/yourDb" -s public --useAllTables

Output to stdout instead of a file:

mermerd -c "postgresql://user:password@localhost:5432/yourDb" -s public --useAllTables --outputMode stdout

Select specific tables without interaction:

mermerd -c "postgresql://user:password@localhost:5432/yourDb" -s public --selectedTables article,article_label

Include enum values, column comments, and NOT NULL in descriptions:

mermerd -c "postgresql://user:password@localhost:5432/yourDb" -s public --useAllTables --showDescriptions enumValues,columnComments,notNull

Reference: mermerd command-line flags

master

The following flags are available for configuring mermerd via the CLI. You can view the full help menu by running mermerd -h.

-c, --connectionString string       connection string that should be used
      --debug                         show debug logs        
  -e, --encloseWithMermaidBackticks   enclose output with mermaid backticks (needed for e.g. in markdown viewer)
  -h, --help                          help for mermerd
      --ignoreTables strings          ignore the given tables (supports regex)
      --omitAttributeKeys             omit the attribute keys (PK, FK, UK)
      --omitConstraintLabels          omit the constraint labels
  -o, --outputFileName string         output file name (default "result.mmd")
      --outputMode OutputModeType     output mode (file, stdout) (default file)
      --runConfig string              run configuration (replaces global configuration)
  -s, --schema string                 schema that should be used
      --schemaPrefixSeparator string  the separator that should be used between schema and table name (default ".")
      --selectedTables strings        tables to include
      --showAllConstraints            show all constraints, even though the table of the resulting constraint was not selected
      --showDescriptions strings      show 'notNull', enumValues' and/or 'columnComments' in the description column
      --showSchemaPrefix              show schema prefix in table name
      --useAllSchemas                 use all available schemas
      --useAllTables                  use all available tables
      --relationshipLabels strings    use a different label besides the column name for specific table relationships; overrides `omitConstraintLabels` if specified

Configure mermerd via CLI flags

master

You can control the behavior of mermerd using several flags. Below is a reference of the available flags:

--runConfig string        run configuration (replaces global configuration)
--showAllConstraints      show all constraints, even though the table of the resulting constraint was not selected
--useAllTables             use all available tables
--ignoreTables []string    ignore the given tables (supports regex)
--useAllSchemas           use all available schemas
--debug                    show debug logs
--omitConstraintLabels    omit the constraint labels
--omitAttributeKeys        omit the attribute keys (PK, FK, UK)
--showSchemaPrefix         show schema prefix in table name
--encloseWithMermaidBackticks, -e  enclose output with mermaid backticks (needed for e.g. in markdown viewer)
--connectionString, -c string     connection string that should be used
--schema, -s string           schema that should be used
--outputFileName, -o string   output file name (default: result.mmd)
--schemaPrefixSeparator string the separator that should be used between schema and table name (default: .)
--outputMode (file, stdout)   output mode (file, stdout)
--showDescriptions []string  show 'notNull', 'enumValues' and/or 'columnComments' in the description column
--selectedTables []string     tables to include

Check the mermerd version
master
Use the version command to print the current version number and the git commit hash of the mermerd binary. This is useful for verifying installations or debugging specific builds.
```
mermerd version
```
https://github.com/karnerth/mermerd/blob/master/cmd/version.go

mermerd

What's inside mermerd

Using Go