Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/KarnerTh/mermerd

Create Mermaid-Js ERD diagrams from existing tables
https://github.com/KarnerTh/mermerd

erd erdiagram mermaid mermaidjs

Last synced: 9 days ago
JSON representation

Create Mermaid-Js ERD diagrams from existing tables

Awesome Lists containing this project

README 

        
# Mermerd

[![tests](https://github.com/KarnerTh/mermerd/actions/workflows/test.yml/badge.svg)](https://github.com/KarnerTh/mermerd/actions/workflows/test.yml)



Create [Mermaid-Js](https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram) ERD diagrams from existing tables.



Want to see what has changed? Take a look at

the [Changelog](https://github.com/KarnerTh/mermerd/blob/master/changelog.md)



# Contents




## Installation

```sh

go install github.com/KarnerTh/mermerd@latest

```



or



just head over to the [Releases](https://github.com/KarnerTh/mermerd/releases) page and download the right executable

for your operating system. To be able to use it globally on your system, add the executable to your path.



## Features



* Supports PostgreSQL, MySQL, MSSQL and Sqlite3

* Select from available schemas

* Select only the tables you are interested in

* Show only the constraints that you are interested in

* Interactive cli (multiselect, search for tables and schemas, etc.)

* Use it in CI/CD pipeline via a run configuration

* Either generate plain mermaid syntax or enclose it with mermaid backticks to use directly in e.g. GitHub markdown

* Show primary keys, foreign keys, and unique constraints

* Show enum values of enum column

* Show column comments

* Show NOT NULL constraints



## Why would I need it / Why should I care?



Documenting stuff and keeping it updated is hard and tedious, but having the right documentation can help to make the

right decisions. Mermerd was designed to be able to export an existing database schema in a format that can be used to

prototype and plan new features based on the existing schema. The resulting output is an ERD diagram

in [Mermaid-Js](https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram) format that can easily be updated and

extended.



## How does it work



1. Specify the connection string (via parameter or interactive cli)

2. Specify the schema that should be used (via parameter or interactive cli)

3. Select the tables that you are interested in (multiselect, at least 1)

4. Enjoy your current database schema in Mermaid-JS format



https://user-images.githubusercontent.com/22556363/149669994-bd5cfd8d-670c-4f64-9fe9-4892866d6763.mp4



## Parameters/Flags



Some configurations can be set via command line parameters/flags. The available options can also be viewed

via `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")

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

```



If the flag `--showAllConstraints` is provided, mermerd will print out all constraints of the selected tables, even when

the resulting constraint is not in the list of selected tables. These tables do not have any column info and are only

present via their table name.



## Global configuration file



Mermerd uses a yaml configuration file in your home directory called `.mermerd` (needs to be created, an example is

shown below). You can set options that you want by default (e.g. enabling the `showAllConstraints` for all runs) or

provide connection string suggestions for the cli.



```yaml

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

```



## Use a predefined run configuration (e.g. for CI/CD)



You can specify all parameters needed for generating the ERD via a run configuration. Just create a yaml file (example

shown below) and start mermerd via `mermerd --runConfig yourRunConfig.yaml`



```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"

debug: true

omitConstraintLabels: true

omitAttributeKeys: true

showDescriptions:

  - enumValues

  - columnComments

  - notNull

showSchemaPrefix: true

schemaPrefixSeparator: "_"

ignoreTables:

  - city



# Names must match the pattern 

relationshipLabels:

  - "public_table public_another-table : label"

```



## Example usages



```bash

# all parameters are provided via the interactive cli

mermerd



# same as previous one, but show all constraints even though the table of the resulting constraint was not selected

mermerd --showAllConstraints



# ERD is created via the provided run config

mermerd --runConfig yourRunConfig.yaml



# specify all connection properties so that only the table selection is done via the interactive cli

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



# same as previous one, but use all available tables without interaction

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



# same as previous one, but use a list of tables without interaction

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



# show enum values, column comments and notNull in the description column

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

```



## Connection strings



Examples of valid connection strings:



* `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`



#### Special Characters

Passwords with special characters may run into the "net/url: invalid userinfo" error. This can be worked around by percent encoding the characters



| Invalid | Valid                                                        |

|-----|----------------------------------------|

|postgresql://user:password$@localhost:5432/yourDb|postgresql://user:password%24@localhost:5432/yourDb

|postgresql://user:pass[];$/word@localhost:5432/yourDb|postgresql://user:pass%5B%5D%3B%24%2Fword@localhost:5432/yourDb



## How can I write/update Mermaid-JS diagrams?



* All information can be found here: [Mermaid-JS](https://mermaid-js.github.io/mermaid/#/entityRelationshipDiagram)

* I also recommend using an IDE with a Mermaid-JS extension,

  e.g. [VS Code](https://marketplace.visualstudio.com/items?itemName=tomoyukim.vscode-mermaid-editor)



## How does mermerd determine the constraints?



The table constraints are analysed and interpreted as listed:



| Nr. | Constraint type                        | Criteria                                                                 |

|-----|----------------------------------------|--------------------------------------------------------------------------|

| 1   | a |o--|| b | If table a has a FK to table b and that column is the only PK of table a |

| 2   | a }o--|| b      | Same as 1, but table a has multiple PK                                   |

|     |                                        | Same as 1, but the FK is not a PK                                        |

| 3   | a }o--o| b           | Same as 2, but the FK is nullable                                        |



## Tests



You can either use the Makefile targets to run the tests and have a pretty

output ([tparse](https://github.com/mfridman/tparse) is used for formatting) or start them manually via `go test`.



Mocks for unit tests are generated via [mockery](https://github.com/vektra/mockery) (can be created

via `make create-mocks` or `mockery --all`)



Local setup for integration tests:



1. `cd test`

2. `docker-compose up -d`

3. done - the required tables are created automatically at startup (`test/db-table-setup.sql` contains all test data)



Integration and unit tests are separated via the `--short` flag:



* `go test --short -v ./...` runs all unit tests

* `go test -v ./...` runs all unit and integration tests



or via the Makefile targets



* `make test-unit` runs all unit tests

* `make test-all` runs all unit and integration tests



## Roadmap



* [ ] Support `}o--o|` relation (currently displayed as `}o--||`)

* [ ] Take unique constraints into account