Entity-Relationship Diagrams for Ruby on Rails Rails ERD

Since version 2.0, Rails ERD generates Mermaid diagrams by default. Mermaid is a text-based diagramming format that renders natively on GitHub, GitLab, Notion, and many documentation tools — with no external dependencies to install. Continue to read how to install Rails ERD so you can start creating model diagrams.

Install Rails ERD

Rails ERD requires Ruby 3.1+ and Active Record 7.0+ (Rails 7.x and 8.x are supported). Add Rails ERD to your Ruby on Rails application. In your Gemfile...

group :development do
  gem "rails-erd"
end

Bundler will install everything you need...

% bundle install

Generate your first diagram

You now have a new Rake task in your application. Generate an up-to-date model diagram with...

% rake erd

Done! This generates a Mermaid diagram in erd.mmd by default, which you can paste into any Markdown file (it renders inline on GitHub and GitLab) or view in a Mermaid renderer such as mermaid.live. Not completely satisfied? You can customise the output.

Want PDF, PNG, or SVG output?

The Mermaid generator has no external dependencies. If you'd rather produce PDF, PNG, or SVG output, use the optional Graphviz generator. You'll need Graphviz 2.22+ installed…

% brew install graphviz           # Homebrew on macOS
% sudo port install graphviz      # MacPorts on macOS
% sudo apt-get install graphviz   # Debian and Ubuntu

…plus the ruby-graphviz gem in your Gemfile. Then select the Graphviz generator when you generate the diagram...

% rake erd generator=graphviz filetype=pdf

Not using Rails?

If you use Active Record outside of a Rails application, you can also use Rails ERD to create model diagrams for you. Install the rails-erd gem, load your models, and execute...

# Make sure all your models are loaded.
require "rails_erd/diagram/mermaid"

RailsERD::Diagram::Mermaid.create

Having trouble?

If Rails ERD doesn't work like you expected it to, don't give up immediately. The default Mermaid output is plain text, so start by generating it and inspecting the result...

% rake erd

Open the generated erd.mmd and check that it's not empty. If it looks reasonable, Rails ERD is probably working fine, and any rendering problem is in the tool displaying the Mermaid (try mermaid.live). If you're using the Graphviz generator instead and the output looks wrong, try generating raw dot instructions with rake erd generator=graphviz filetype=dot and inspecting erd.dot, or upgrade to a recent version of Graphviz.

If things are still not running smoothly, I'd love to hear from you. You can either create a new issue, or drop me a line at r.timmermans at voormedia.com. If something goes wrong while generating a diagram, please provide a set of example models that exhibit the problem.