rails-erd says Rails 6 and later, then requires ActiveRecord 7.0

Mermaid by default since 2.0, Graphviz when you want a PDF

The output format changed with the major version, and it is the most consequential thing in the file. Since version 2.0 the default is a Mermaid diagram written to `erd.mmd`, which renders natively in GitHub, GitLab and many documentation tools. That means the diagram can live in the same README as the code it describes, with no build step and no image hosting.

The older path is still there for anyone who needs a real image. Graphviz produces PDF, PNG and SVG output with styling, and a gallery page collects examples of what those look like. Choosing it costs a system dependency: Graphviz 2.22 or newer on the machine, plus the `ruby-graphviz` gem, and then two flags on the command, `--generator=graphviz` and `--filetype=pdf`.

The support sentence and the requirement list disagree

One paragraph says the gem was created for Rails and works on versions 6.0 and later, explicitly including 7.x and 8.x. A few lines further down, the requirements list Ruby 3.1 or newer, ActiveRecord 7.0 or newer, and Graphviz 2.22 or newer as optional.

An application on Rails 6 satisfies the first statement and fails the second, since Rails 6 ships an Active Record older than 7.0. Nothing in the file resolves the contradiction, so the requirement line is the one to plan against: Ruby 3.1 plus ActiveRecord 7.0 is the real floor, and the Rails 6 mention is either stale or refers to something looser than the declared requirement.

One gem in the development group, one command

The install summary is two steps. Add `gem 'rails-erd', group: :development` to the application's Gemfile, then run `bundle exec erd`, which writes the Mermaid file. Restricting it to the development group is deliberate: a diagram is a development artefact, and the gem should not be a runtime dependency of the application.

Switching to image output adds two more steps rather than a flag alone, because the generator is a separate program. Graphviz has to be present on the system, installed on macOS with Homebrew or on Linux with the distribution's package manager, and `ruby-graphviz` has to be in the Gemfile. Only then does `bundle exec erd --generator=graphviz --filetype=pdf` produce a PDF, which is why the requirements call Graphviz optional rather than absent.

Configuration is read from your home directory first, then the project

Settings come from the command line or from a YAML file, and the file lookup order matters. Rails ERD looks for `~/.erdconfig` first and then `./.erdconfig`, and the project file overrides whatever the home file set. That is the shape you want for a diagram that differs per repository while keeping personal defaults out of version control.

The file in the README is the full default set, and it is a useful thing to read even if you change nothing, because it names every dial the gem has:

attributes:
  - content
disconnected: true
filename: erd
filetype: mmd
generator: mermaid
indirect: true
inheritance: false
markup: true
mermaid_style: erdiagram
notation: simple
orientation: horizontal
polymorphism: false
recursive: true
sort: true
warn: true
title: true
exclude: null
exclude_attributes: null
only: null
only_attributes: null
only_recursion_depth: null
prepend_primary: false
cluster: false
splines: spline

The list also explains why diagrams of mature applications look the way they do: recursion is on, sorting is on, indirect `has_many :through` relationships are included, and clustering is off.

Three pattern languages for exclude and only

Both `exclude` and `only` accept three kinds of pattern, and the oldest is kept for compatibility. An exact match is the original behaviour, where the model name has to match exactly. A glob pattern uses `*` for any run of characters, `?` for a single character and square brackets for a character class, which is what you want for dropping a whole namespace such as a job queue, a reporting engine or an analytics gem in one line.

A regular expression is written between slashes, and supports the `i`, `m` and `x` flags, with any other flag ignored. The README is explicit about two failure modes worth planning for: a glob containing `*` should be quoted in YAML to avoid parsing trouble, and an invalid regular expression raises an error rather than being skipped. When both keys are present, `only` is applied first and `exclude` second, so an `only` list narrows the diagram and `exclude` then removes from what is left.

Attribute filtering is per model, and the option has two spellings

The `attributes` key chooses which kinds of attributes appear for every model, and two more keys refine that per model. `only_attributes` maps a model name to the attributes to keep, `exclude_attributes` maps a model name to the attributes to hide, and any model not named in either map keeps all of its attributes. Hiding everything for one model is expressed as a boolean `true` rather than a list of every column.

The invocation differs by entry point, and the README shows both. Through the rake task the options are bare key and value pairs, while the `erd` binary requires the `--` prefix on the same names:

# rake task (bare key=value)
bundle exec rake erd only_attributes="Book.title,Book.isbn"
bundle exec rake erd exclude_attributes="BigTable,User.password_digest,User.remember_token"

The binary form that follows stops partway through its first quoted value, so the flag spelling is the one to infer rather than read off the page.

The bundled preview diagram stops in the middle of an attribute

The preview section shows a Mermaid diagram generated from the Event Forms application, one of the bundled examples, and notes that dotted lines are indirect `has_many :through` relationships. The listing itself ends inside the Group model, on a line that reads `st` after the attribute list, so the diagram in the README is cut off in the middle of a model.

The examples directory is more complete than the preview. It holds separate applications for associations, domains, entities, inheritance, meta and polymorphism, two example configuration files, and small Ruby scripts including `identity.rb`, `sfdp.rb` and `generate.rb`, which look like direct exercises of the gem's API. A `gemfiles/` directory at the root suggests the test matrix runs against several dependency sets, which is the usual reason a Rails gem accumulates that many files.

Three releases in eleven weeks, titled after the features

The three most recent tags are named after what they changed rather than after a version number alone: v2.0.2 is Less Is More, v2.1.0 is Cluster Party, and v2.2.0 is No Loops, No Phantoms. They shipped on 11 June, 10 July and 27 August 2026, and the most recent commit carries the same timestamp as the last of them.

The titles map onto options you can see in the configuration file. Clustering is one of the documented keys and is off by default, so v2.1.0 is plausibly where it arrived; recursion is on by default, and a release named for removing loops and phantoms is plausibly about stopping the diagram chasing a relationship cycle. That is inference from the titles rather than a changelog claim, and the file `CHANGES.md` at the root is where the actual entries live.

The repository also records a single open issue against more than 4100 stars, which is either a well moderated tracker or an unusually quiet one, and it carries a `CODE_OF_CONDUCT.md`, a `.gemtest` file and a `.pryrc` for an interactive console session. Three releases in eleven weeks with one open issue is a project shipping quickly and receiving few reports.

Editorial conclusion

rails-erd is a good fit for a Rails application whose models are documented in the repository rather than in a separate tool, because the default output renders in the places people already read, and because the filtering options are fine grained enough to hide a framework's twenty tables without hand editing the diagram. Two things to settle before you rely on it. First, the support statement and the requirement line disagree: the README says it works on Rails 6.0 and later while the requirements list ActiveRecord 7.0 as the floor, so check your own version against the requirement rather than the prose. Second, Graphviz is optional and only needed for PDF and PNG, which is worth knowing before you install it expecting it to be used. And if you filter with regular expressions, an invalid pattern raises an error rather than being ignored, so test your patterns in a scratch config.

Frequently asked questions

Official sources

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