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

View Source

A Mix task that generates an ERD (Entity‑Relationship Diagram) in various formats.

Supported formats:

Configuration examples and sample output for a few open-source projects can be found in the PAGES section under EXAMPLES.

DOT

The DOT format can represent all available entity types:

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

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

Install Graphviz to convert a *.dot file to an 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 supports the same features as DOT.

Install PlantUML to convert a *.puml file to an 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 the output image is cropped, adjust the image size with the PLANTUML_LIMIT_SIZE environment variable.

DBML

The DBML format is more limited than DOT and PlantUML, as it focuses on tables only. Multiple schemas that use the same table are merged into one. Embedded schemas cannot be displayed. TableGroups are supported and can be set via the :map_node option using Ecto.ERD.Node.set_cluster/2.

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

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

QuickDBD

A format used by QuickDBD, a competitor of dbdiagram.io. Like DBML, it focuses 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 compared to DOT and PlantUML and focuses on tables only. Multiple schemas that use the same table are merged into one. 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, you can convert the output *.mmd file to an image using the following command:

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

The default -w and -H values are small (800 and 600, respectively), so it's better to provide larger values from the start.

Command line options

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

Configuration file

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

Options

  • :fontname - font name. Defaults to Roboto Mono. Must be a monospaced font if the output format is dot and more than one column is displayed. Supported only for dot and puml files.
  • :columns - list of columns displayed for each node (schema/source). Set to [] to hide fields completely. Available columns: :name, :type. Supported for dot, puml, and mmd (mmd allows only [] or the default value). Default values:
    • [:name, :type] for dot and puml
    • [:type, :name] for mmd
  • :map_node - a function that removes a node from the diagram or assigns it to a cluster. Defaults to Function.identity/1, which means all nodes are displayed outside any cluster by default. Use Ecto.ERD.Node.set_cluster/2 in this function to set a cluster. Supported only by DOT, PlantUML, and DBML. Return nil to remove a node from the diagram.
  • :otp_app - the application to scan (along with its dependencies) to collect Ecto schemas. Defaults to Mix.Project.config()[:app]. Configure this only when running the task from an umbrella root.

A configuration file with default values for dot and puml can look like this:

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