Rails ERD: Generating Entity-Relationship Diagrams from Active Record Models

The gap Rails ERD fills between schema.rb and a real domain picture

schema.rb tells you which columns exist and which foreign keys point where. It does not tell you that Event reaches EventDate through a has_many :through, or that Organization owns Group which owns Event. Those relationships live in the model layer, expressed as association declarations, and they are the part of a Rails application that stops fitting in a developer's head somewhere around the thirtieth model.

Rails ERD targets exactly that layer. The README states the gem "allows you to easily generate a diagram based on your application's Active Record models," and names two goals: documentation of how models relate, and inspection of the domain model. The audience is Rails developers working on an existing application, plus anyone who has to explain that application's structure to a new team member. The README also notes the gem was "created specifically for Rails and works on versions 6.0 and later (including Rails 7.x and 8.x)." That specificity is the point. This is not a database introspection tool that happens to understand Rails; it is a Rails tool that reads Active Record's own metadata.

How Rails ERD reads your models: Active Record reflection, then a renderer

The mechanism the README names is Active Record reflection. Rails already knows every association on every model, because the macros that declare them store that information in the class. Rails ERD walks that reflection data, collects entities and their attributes, and then hands the result to a generator.

Since version 2.0 the default generator is Mermaid. The README says Rails ERD "generates Mermaid diagrams by default, which render natively on GitHub." The example in the README shows the shape of that output: an erDiagram block with a direction, one stanza per entity listing column names and types, and relationship lines such as Organization ||--}o Group. The cardinality markers are Mermaid's own notation. The README notes that dotted lines in that example are indirect has_many :through relationships, so the diagram distinguishes direct associations from ones routed through a join model.

The second generator wraps Graphviz and produces PDF, PNG or SVG. That path is optional and requires the ruby-graphviz gem plus a Graphviz binary on the machine. The README describes the Graphviz output as "richly styled diagrams." The trade-off is real: Mermaid output is plain text that diffs cleanly in Git and renders on GitHub, while Graphviz output looks better in a document but is a binary artifact you regenerate rather than review.

Installing rails-erd and drawing your first diagram

Add the gem to the development group of your Gemfile. The README gives this exact line:

gem 'rails-erd', group: :development

Then install it:

bundle install

With the gem in place, run the generator from your application root:

bundle exec erd

According to the README, this writes a Mermaid diagram to erd.mmd. Open that file and you should see an erDiagram block listing your models as entities with their column names and types, followed by relationship lines between them. Commit it if you want the diagram to render on GitHub, since Mermaid renders natively there.

If you need a PDF or PNG instead, the Graphviz path has extra prerequisites. The README lists Graphviz 2.22+ as optional, needed only for PDF and PNG output, and gives these install commands:

brew install graphviz

sudo apt-get install graphviz

Add ruby-graphviz to the Gemfile, then switch generators and file type on the command line:

bundle exec erd --generator=graphviz --filetype=pdf

For anything beyond the defaults, Rails ERD reads a YAML config file. The README says it looks first at ~/.erdconfig and then at ./.erdconfig, with the project-local file overriding the home-directory one. The same page prints the full default set, including filename: erd, filetype: mmd, generator: mermaid, indirect: true, polymorphism: false and cluster: false. Copying that block into ./.erdconfig and editing individual keys is the intended way to change behaviour without retyping flags.

Filtering noise with exclude, only, and the attribute options

A real Rails application's reflection graph includes tables nobody wants in a domain diagram: ActiveStorage, SolidQueue, Blazer, Ahoy. Rails ERD addresses this with exclude and only, and the pattern support is more capable than a plain model-name list. Three pattern types are supported.

Exact match is the backward-compatible form, where the model name must match exactly. Glob patterns use * for any characters, ? for a single character, and [...] for character classes. Regex patterns are wrapped in forward slashes and support the i, m and x flags. The README's own examples show all three, including excluding an entire namespace with a quoted glob and matching a prefix with a regex. Patterns containing * should be quoted in YAML to avoid parsing problems, and the README warns that invalid regex patterns raise an error, so a typo fails the run rather than silently matching nothing.

Two details matter for predicting output. Only i, m and x regex flags are supported and other flags are ignored, which means a pattern that relies on an unsupported flag will behave differently than you expect without telling you. And when both exclude and only are specified, only is applied first, then exclude. That ordering is worth remembering: a model that survives the only filter can still be removed by a later exclude rule.

Attributes get their own layer. The attributes option selects which kinds of attributes appear for every model, while only_attributes and exclude_attributes refine that per model, keyed by model name. The README describes them as mirroring the way only and exclude filter entities. In practice this is how you keep a wide table from turning its entity box into a wall of column names.

Where Rails ERD stops being the right tool

The most obvious limitation is the one the README states outright: Rails ERD was created specifically for Rails. If your application is not a Rails application, or if its models do not use Active Record, there is nothing for the reflection pass to read. A Sinatra app with Sequel, a Django project, or a database you only have a connection string for are all outside the tool's reach.

The version floor is a second boundary. The README lists Ruby 3.1+ and ActiveRecord 7.0+ as requirements. An application pinned to an older Rails cannot use current Rails ERD, and the README does not describe a supported path for older versions.

The Graphviz path carries its own failure mode. Graphviz is optional for Mermaid output but required for PDF and PNG, and the README does not document what happens when the binary is missing or older than 2.22. Since the Graphviz route also needs the ruby-graphviz gem added separately, a team that copies a --generator=graphviz command from a blog post without adding that gem will hit an error the README's getting-started summary does not walk through.

Finally, the diagram is a snapshot. Rails ERD reads the models as they are at the moment you run it. Nothing in the README describes a watcher, a hook, or CI integration that keeps erd.mmd current, so the diagram's accuracy depends entirely on someone remembering to regenerate it after association changes.

Rails ERD against Railroady and hand-written Mermaid

Railroady is the closest alternative, and the difference is not cosmetic. Railroady is a separate Ruby gem that also draws Rails models, but it grew up around Graphviz output and its own model-loading approach. Rails ERD's distinguishing decision is the one made in version 2.0: Mermaid is the default output format, not Graphviz. That choice changes the workflow more than the picture. Mermaid output is text, so it lives in the repository, shows up in pull request diffs, and renders on GitHub without a build step or a binary artifact. A Graphviz-first tool produces an image you attach or publish, which is harder to review and easy to let go stale.

The other alternative is writing the Mermaid erDiagram block by hand. That gives you full control over layout, grouping and which relationships to show, and it costs nothing to install. What you lose is the connection to reality: a hand-written diagram is correct only until someone adds an association, and nothing tells you it has drifted. Rails ERD's value is that the diagram is derived from the same reflection data the application runs on, so regenerating it is cheaper than proofreading it.

Licence, maintenance and what upgrading costs you

Rails ERD is MIT licensed. In practical terms that is a permissive licence, and the repository ships a LICENSE.md alongside the gemspec. Nothing here is legal advice; if your organization has rules about which licences may enter a dependency tree, the MIT text in LICENSE.md is the thing to check.

On maintenance, the last push to the default branch was on 2026-08-27, and the most recent release listed is v2.2.0 on the same date. The repository is not archived. Recent releases have arrived at a steady cadence through mid-2026, and the version notes are informal, with v2.2.0 titled "No Loops, No Phantoms" and v2.1.0 titled "Cluster Party." Those titles hint at what changed but the README does not spell out the migration impact of either.

The upgrade cost sits mostly in configuration rather than code. Rails ERD is a development-group gem; it does not ship in production, so a version bump cannot break a running application. What a bump can change is output. The move to Mermaid as the default generator in version 2.0 is the clearest example: a project that relied on the old default and never pinned a generator in .erdconfig would find its output format changed after upgrading. Teams that care about the diagram's format should set generator and filetype explicitly in ./.erdconfig rather than inheriting defaults that future releases may revise.

Editorial conclusion

Adopt Rails ERD if you maintain a Rails application whose associations have grown hard to hold in your head, and you want a diagram you can regenerate after each schema change without leaving the terminal. Skip it if your models are not Active Record, or if you need a diagram of a database you cannot boot in Ruby. Before trusting the output, check three things: that your indirect associations appear as dotted lines, that the Graphviz binary on your machine is at least version 2.22 if you want PDF or PNG, and that your .erdconfig exclude patterns hide the framework tables you do not want in the picture.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. voormedia/rails-erd on GitHub