mix ecto.gen.erd (Ecto ERD v0.6.3)

View Source

A mix task to generate an ERD (Entity Relationship Diagram) in various formats.

Supported formats:

Configuration examples and output for a couple of open-source projects can be found in EXAMPLES group of PAGES section.

DOT

DOT format is able to represent all available types of entities:

  • schemas
  • embedded schemas
  • schemaless tables (automatically derived from many-to-many relations)

Clusters are supported and can be set in :map_node option using Ecto.ERD.Node.set_cluster/2.

You should have installed graphviz in order to convert *.dot file to image.

$ mix ecto.gen.erd # generates ecto_erd.dot
$ mix ecto.gen.erd --output-path=ecto_erd.dot
$ mix ecto.gen.erd && dot -Tpng ecto_erd.dot -o erd.png && xdg-open erd.png

PlantUML

PlantUML is equal to DOT in number of supported features.

You should have installed plantuml in order to convert *.puml file to image.

$ mix ecto.gen.erd --output-path=erd.puml
$ mix ecto.gen.erd --output-path=erd.puml && plantuml erd.puml && xdg-open erd.png

Tip: if output image is cropped, you may need to adjust image size with PLANTUML_LIMIT_SIZE environment variable.

DBML

DBML format is more limited in number of displayed entity types comparing to DOT and PlantUML, as it is focused on tables only. Multiple schemas that use the same table are merged into one table. Embedded schemas, obviously, cannot be displayed at all. TableGroups are supported and can be set in :map_node option using Ecto.ERD.Node.set_cluster/2.

This format is very handy if you use dbdiagram.io or dbdocs.io.

$ mix ecto.gen.erd --output-path=ecto_erd.dbml

QuickDBD

A format that is used by QuickDBD - a competitor of dbdiagram.io. Similarly to DBML, it is also focused on tables and cannot display embedded schemas. However, this format doesn't support clusters.

It doesn't have a reserved file extension, but we use *.qdbd.

$ mix ecto.gen.erd --output-path=ecto_erd.qdbd

Mermaid

Mermaid is also limited, comparing to DOT and PlantUML, and focused on tables only. Multiple schemas that use the same table are merged into one table. Embedded schemas, cannot be displayed. Clusters are not supported. The benefit of this format is that it is supported by Github.

$ mix ecto.gen.erd --output-path=ecto_erd.mmd

If you have installed mermaid-cli locally, the output *.mmd file can be converted to image using the following command:

$ mmdc -i ecto_erd.mmd -o erd.png -w 6000 -H 6000

Default -w and -H values are quite small (800 and 600 respectively), so it is better to provide bigger values from the very beginning.

Command line options

  • --output-path - the path to the output file, defaults to ecto_erd.dot. Supported file extensions: dot, puml, dbml, qdbd.
  • --config-path - the path to the config file, defaults to .ecto_erd.exs.

Configuration file

When running a mix ecto.gen.erd task, it tries to read a configuration file from the .ecto_erd.exs file in a current working directory. Configuration file must return a keyword list.

Options

  • :fontname - font name, defaults to Roboto Mono. Must be monospaced font if output format is dot and more than 1 column is displayed. The option is only supported for dot and puml files.
  • :columns - list of columns which will be displayed for each node (schema/source). Set to [] to hide fields completely. Available columns: :name and :type. The option is only supported for dot, puml and mmd(mmd only allows usage of [] and the default value). Default values:
    • [:name, :type] for dot and puml.
    • [:type, :name] for mmd
  • :map_node - function which allows to remove the node from the diagram or to move the node to the cluster. Defaults to Function.identity/1, which means that all nodes should be displayed and all of them are outside any cluster. Use Ecto.ERD.Node.set_cluster/2 in this function to set a cluster. Only supported by DOT, PlantUML and DBML. In order to remove the node from diagram, the function must return nil.
  • :otp_app - an application which will be scanned alongside with dependent applications in order to get a list of Ecto schemas. Defaults to Mix.Project.config()[:app]. You need to configure this option only if you run a task from the umbrella root.

Configuration file file with default values for dot and puml can be represented as follows:

# .ecto_erd.exs
[
  fontname: "Roboto Mono",
  columns: [:name, :type],
  map_node: &Function.identity/1,
  otp_app: Mix.Project.config()[:app]
]