Create Mermaid-Js ERD diagrams from existing tables.
Want to see what has changed? Take a look at the Changelog
- Installation
- Features
- Why would I need it / Why should I care?
- How does it work
- Parameters/Flags
- Global configuration file
- Use a predefined run configuration (e.g. for CI/CD)
- Example usages
- Connection strings
- How can I write/update Mermaid-JS diagrams?
- How does mermerd determine the constraints?
- Tests
- Roadmap
go install github.com/KarnerTh/mermerd@latest
or
just head over to the 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.
- 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
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 format that can easily be updated and extended.
- Specify the connection string (via parameter or interactive cli)
- Specify the schema that should be used (via parameter or interactive cli)
- Select the tables that you are interested in (multiselect, at least 1)
- Enjoy your current database schema in Mermaid-JS format
example.mp4
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.
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.
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:https://user:password@localhost:5432/yourDb
- mysql:https://root:password@tcp(127.0.0.1:3306)/yourDb
- sqlserver:https://user:password@localhost:1433?database=yourDb
- sqlite3:https://mermerd_test.db
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
# Connection properties
connectionString: "postgresql:https://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 <schema><schema_prefix><table>
relationshipLabels:
- "public_table public_another-table : label"
# 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:https://user:password@localhost:5432/yourDb" -s public
# same as previous one, but use all available tables without interaction
mermerd -c "postgresql:https://user:password@localhost:5432/yourDb" -s public --useAllTables
# same as previous one, but use a list of tables without interaction
mermerd -c "postgresql:https://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:https://user:password@localhost:5432/yourDb" -s public --useAllTables --showDescriptions enumValues,columnComments,notNull
Examples of valid connection strings:
postgresql:https://user:password@localhost:5432/yourDb
mysql:https://root:password@tcp(127.0.0.1:3306)/yourDb
sqlserver:https://user:password@localhost:1433?database=yourDb
sqlite3:https://mermerd_test.db
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:https://user:password$@localhost:5432/yourDb | postgresql:https://user:password%24@localhost:5432/yourDb |
postgresql:https://user:pass[];$/word@localhost:5432/yourDb | postgresql:https://user:pass%5B%5D%3B%24%2Fword@localhost:5432/yourDb |
- All information can be found here: Mermaid-JS
- I also recommend using an IDE with a Mermaid-JS extension, e.g. VS Code
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 |
You can either use the Makefile targets to run the tests and have a pretty
output (tparse is used for formatting) or start them manually via go test
.
Mocks for unit tests are generated via mockery (can be created
via make create-mocks
or mockery --all
)
Local setup for integration tests:
cd test
docker-compose up -d
- 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 testsgo test -v ./...
runs all unit and integration tests
or via the Makefile targets
make test-unit
runs all unit testsmake test-all
runs all unit and integration tests
- Support
}o--o|
relation (currently displayed as}o--||
) - Take unique constraints into account