Entity-Relationship Diagrams for Ruby on Rails Rails ERD

Rails ERD supports several customisation options, all of which can be provided on the command line. Even if you're completely unhappy with the output, you can still use Rails ERD. It has a powerful API that you can use to inspect your domain models, or to easily generate output in the format of your choice.

Providing options

% rake erd orientation=vertical title='My model diagram'

Available options

generator              mermaid | graphviz

Selects the diagram generator. The mermaid generator (the default) produces text-based Mermaid diagrams that render natively on GitHub and GitLab, with no external dependencies. The graphviz generator produces PDF/PNG/SVG output and requires the ruby-graphviz gem and a Graphviz installation. Default value: mermaid

mermaid_style          erdiagram | classdiagram

Only applies to the Mermaid generator. The erdiagram style (the default) uses Mermaid's erDiagram syntax with crow's foot notation and PK/FK markers. Set to classdiagram to use classDiagram syntax instead. Default value: erdiagram

attributes             <type,...> | false

Specifies which attributes to include in the diagram output. This can be any combination of the following attribute types:

foreign_keys

any foreign key column in use for associations

primary_keys

the primary key column (typically id)

timestamps

any of the 'magic' timestamp columns (created_at/on, updated_at/on)

inheritance

the single table inheritance column (typically type)

content

all other columns

To hide attributes altogether, set this option to false. Default value: content

disconnected           true | false

Specifies whether or not to display disconnected entities. An entity is disconnected if it has no relationships with any other entity. Default value: true

filename               <string>

The file basename of the generated diagram. Together with the file type, this will determine the file name of the output. Default value: erd

filetype               mmd | pdf | png | svg | dot | ...

The file type of the generated diagram. With the default Mermaid generator this is mmd (a Mermaid text file). With the Graphviz generator, PDF output is recommended; the available formats depend on your installation of Graphviz. If you set the file type to dot, raw Graphviz instructions are saved in dot format. Default value: mmd

indirect               true | false

Specifies whether or not to display relationships that are indirect. Indirect relationships are defined in Active Record by has_many :through associations. Default value: true

inheritance            true | false

Specifies whether or not to display inheritance hierarchies. Single table inheritance in Rails is usually transparent and uninteresting in an entity-relationship diagram. In some cases inheritance is central to the domain model, however. For example, subtypes may have their own relationships, which would be hidden otherwise. In those cases it makes a lot of sense to display all subtypes. Default value: false

notation               simple | bachman

The ideal diagram notation may not be the same for everyone. Rails ERD defaults to simple arrows to indicate cardinalities. No difference is made for optional and mandatory relationships (sometimes referred to as participation). This a classic way to draw data structures. It is easy to understand, and provides enough information in most cases.
If you prefer to see the cardinality as well as the participation, try setting this option to bachman. This is a more advanced notation, devised by Charles Bachman in 1992.
For notation examples, browse the gallery. Default value: simple

orientation            horizontal | vertical

Diagrams display entities in a hierarchical way. The hierarchy is defined by the associations on your models. A model that has_one or has_many other models will be higher in the hierarchy. This option causes the hierarchy to run either horizontally or vertically. Which of the two is most appropriate depends on your models, be sure to try both. Default value: horizontal

polymorphism           true | false

Specifies whether or not to display polymorphic hierarchies. Polymorphic associations are normally displayed as direct relationships. In some cases this may be confusing, because it masks their true nature. Enable this option if polymorphic associations play a crucial role in your domain model. Enabling this option will also display abstract classes. Default value: false

title                  true | false | <string>

By default, a title is displayed at the top of the diagram: "<application> domain model". You can change the title by setting this option. If set to false, no title will be displayed at all. Default value: true

warn                   true | false

When set to false, no warnings are printed to the command line while processing models and drawing the diagram. Default value: true

only                   <string>

Only include specified models. Together with exclude, this will allow to filter out models on your diagram. Default value: nil. Example: only="Order,Customer,Product"

exclude                <string>

Exclude specified models. Together with only, this will allow to filter out models on your diagram. Models are matched by exact name. Default value: nil. Example: exclude="User,Role"

only_recursion_depth   <integer>

When used with only, also includes models within this many relationship "hops" of the listed models, instead of only the listed models themselves. Useful for focusing a diagram on one part of a large domain. Default value: nil (no recursion).

exclude_attributes     <hash> | <string>

Hides attributes on a per-model basis (unlike attributes: false, which hides them for every model). Map a model name to true to hide all of its attributes, or to a list of attribute names to hide only those. From the command line, pass a comma separated list where each entry is either Model (hide all) or Model.attribute (hide one). Default value: nil. Example: exclude_attributes="BigTable,User.password_digest"

prepend_primary        true | false

When enabled, lists the primary key attribute first within each entity, instead of in alphabetical order with the other attributes. Default value: false

cluster                true | false

Graphviz generator only. Groups models that share a namespace into visual sub-clusters, which can make large, namespaced domains easier to read. Default value: false

Custom output

Rails ERD provides an abstract class that you can use to implement your own diagram generation code. The following example generates code that can be used with yUML, an online UML diagram service...

require "rails_erd/diagram"

class YumlDiagram < RailsERD::Diagram
  setup { @edges = [] }

  # Invoked once for each relationship
  each_relationship do |relationship|
    line = if relationship.indirect? then "-.-" else "-" end

    arrow = case
    when relationship.one_to_one?   then "1#{line}1>"
    when relationship.one_to_many?  then "1#{line}*>"
    when relationship.many_to_many? then "*#{line}*>"
    end

    @edges << "[#{relationship.source}] #{arrow} [#{relationship.destination}]"
  end

  # Should save or return the generated diagram
  save { @edges * "\n" }
end

Only 14 lines of code! Then, simply call...

YumlDiagram.create
#=> "[Rubygem] 1-*> [Ownership]
#    [Rubygem] 1-*> [Subscription]
#    [Rubygem] 1-*> [Version]
#    [Rubygem] 1-1> [Linkset]
#    [Rubygem] 1-*> [Dependency]
#    [Version] 1-*> [Dependency]
#    [User] 1-*> [Ownership]
#    [User] 1-*> [Subscription]
#    [User] 1-*> [WebHook]"

You can paste the resulting code at yuml.me to generate a diagram. Here's an example.

Domain model API

Rails ERD allows you to use its internal API to inspect your domain model. We give some examples here, but for a complete and up-to-date reference, please see the API documentation.

Suppose we have the following domain model...

class User < ActiveRecord::Base
  has_many :posts
  has_many :comments
end

class Post < ActiveRecord::Base
  belongs_to :user
  has_many :comments
end

class Comment < ActiveRecord::Base
  belongs_to :user
  belongs_to :post
end

We can use Rails ERD to discover some attributes of our domain model.

require "rails_erd/domain"

# Discover all models that are currently loaded...
domain = RailsERD::Domain.generate

# Which entities do we have? Each entity corresponds to a model.
domain.entities
#=> [ #<RailsERD::Domain::Entity @model=Comment>,
#     #<RailsERD::Domain::Entity @model=Post>,
#     #<RailsERD::Domain::Entity @model=User> ]

# Does an entity have relationships with other entities?
domain.entities.first.connected?
#=> true

# Let's see all relationships...
domain.relationships
#=> [ #<RailsERD::Domain::Relationship @source=Post @destination=Comment>,
#     #<RailsERD::Domain::Relationship @source=User @destination=Comment>,
#     #<RailsERD::Domain::Relationship @source=User @destination=Post> ]

# What is the destination entity of the first relationship?
domain.relationships.first.destination
#=> Comment

# Does the relationship run in both directions?
domain.relationships.first.mutual?
#=> true

# Is the relationship a one-to-many relationship?
domain.relationships.first.one_to_many?
#=> true