Rails ERD - Generate Entity-Relationship Diagrams for Rails applications

Tests Code Climate

Rails ERD is a gem that allows you to easily generate a diagram based on your application's Active Record models. The diagram gives an overview of how your models are related. Having a diagram that describes your models is perfect documentation for your application.

The second goal of Rails ERD is to provide you with a tool to inspect your application's domain model. If you don't like the default output, it is very easy to use the API to build your own diagrams.

Rails ERD was created specifically for Rails and works on versions 6.0 and later (including Rails 7.x and 8.x). It uses Active Record's built-in reflection capabilities to figure out how your models are associated.

Preview

Since version 2.0, Rails ERD generates Mermaid diagrams by default, which render natively on GitHub. Here's a diagram generated from the Event Forms application — one of Rails ERD's bundled examples (the dotted lines are indirect has_many :through relationships):

erDiagram
direction LR
Event {
	boolean active
	string costs
	text description
	string duration
	text introduction
	text report
	string speaker
	string target_audience
	string title
	string tutors
}
EventDate {
	string date
	text description
	date expiry_date
	string location
}
Form {
	string name
}
FormField {
	string field_type
	string label
	boolean mandatory
	string name
}
FormFieldValue {
	string key
	string value
}
Group {
	boolean active
	text description
	text email_message
	string email_receiver
	string email_subject
	string title
	string url_slug
}
Organization {
	string domain
	text email_message
	string email_receiver
	string email_subject
	string name
	string phone
	string signup_title
	string subdomain
	string website
}
Signup {
	boolean confirmed
	string email
	text serialized_fields
}
Stylesheet {
	text content
	string name
}
Organization o|--}o Stylesheet : ""
Stylesheet ||--}o Group : ""
EventDate o|--}o Signup : ""
Organization ||--}o Group : ""
Organization o|--}o Form : ""
Organization o|..}o Event : ""
Form ||--}o Group : ""
Group ||--}o Event : ""
Group o|..}o EventDate : ""
Form o|--}o FormField : ""
FormField o|--}o FormFieldValue : ""
Event ||--}o EventDate : ""

Rails ERD can also produce richly styled diagrams with Graphviz (PDF/PNG/SVG):

Entity-Relationship Diagram

Browse the gallery for more example diagrams.

Requirements

  • Ruby 3.1+
  • ActiveRecord 7.0+
  • Graphviz 2.22+ (optional - only needed for PDF/PNG output)

Getting started

See the installation instructions for a complete description of how to install Rails ERD. Here's a summary:

  • Add gem 'rails-erd', group: :development to your application's Gemfile

  • Run bundle exec erd

This generates a Mermaid diagram (erd.mmd) by default. Mermaid diagrams render natively in GitHub, GitLab, and many documentation tools.

For PDF/PNG output (optional):

  • Install Graphviz 2.22+ (how?). On macOS with Homebrew run brew install graphviz, on Linux run sudo apt-get install graphviz.

  • Add gem 'ruby-graphviz' to your Gemfile

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

Configuration

Rails ERD has the ability to be configured via the command line or through the use of a YAML file with configuration options set. It will look for this file first at ~/.erdconfig and then ./.erdconfig (which will override any settings in ~/.erdconfig). More information on customization options can be found in Rails ERD's project documentation.

Here is an example .erdconfig showing the default values:

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

Filtering models with exclude and only

Use exclude to hide specific models from the diagram, or only to show only specific models. Both options support three pattern types:

Exact match — the model name must match exactly (backward compatible):

exclude:
  - AdminUser
  - AuditLog

Glob patterns — use * to match any characters, ? for a single character, or [...] for character classes. This is useful for excluding entire namespaces:

exclude:
  - "SolidQueue::*"      # all SolidQueue models (13+ tables)
  - "Blazer::*"          # all Blazer models
  - "ActiveStorage::*"   # all ActiveStorage models
  - "Ahoy::*"            # all Ahoy analytics models

only:
  - "MyApp::*"           # show only models in MyApp namespace

Regex patterns — wrap the pattern in /slashes/ for regular expression matching. Supports i (case-insensitive), m (multiline), and x (extended) flags:

exclude:
  - "/^Active/"          # models starting with "Active"
  - "/Queue$/i"          # models ending with "Queue" (case-insensitive)
  - "/(Audit|Log)/"      # models containing "Audit" or "Log"

You can mix pattern types in the same configuration:

exclude:
  - "SolidQueue::*"      # glob: entire namespace
  - "/^Active/"          # regex: prefix match
  - InternalTool         # exact: specific model

Notes:

  • Patterns with * should be quoted in YAML to avoid parsing issues
  • Invalid regex patterns will raise an error — test your patterns first
  • Only i, m, x regex flags are supported; other flags are ignored
  • When both exclude and only are specified, only is applied first, then exclude

Filtering attributes with exclude_attributes and only_attributes

The attributes option selects which kinds of attributes are displayed for every model. only_attributes and exclude_attributes refine that per model, mirroring the way only and exclude filter entities: use only_attributes to show just a few attributes of a model, or exclude_attributes to hide a few. Both are keyed by model name, and models that are not listed keep all of their attributes.

Showing only some attributes — map a model name to the attributes to keep:

only_attributes:
  Book:
    - title
    - isbn

Hiding some attributes — map a model name to the attributes to hide, or to true to hide all of them:

exclude_attributes:
  BigTable: true            # hide all attributes for BigTable
  User:                     # hide only these attributes for User
    - password_digest
    - remember_token

From the command line, both take a comma separated list of Model.attribute entries. exclude_attributes additionally accepts a bare Model to hide all of its attributes:

# 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"

# erd binary (flags require the -- prefix)
bundle exec erd --only_attributes="Book.title,Book.isbn"
bundle exec erd --exclude_attributes="BigTable,User.password_digest,User.remember_token"

Notes:

  • Unlike only, listing a model in only_attributes does not affect any other model; unlisted models keep all of their attributes
  • When both are specified for a model, only_attributes is applied first, then exclude_attributes
  • Both narrow down the attributes selected by attributes; naming an attribute in only_attributes does not display it when its kind is not displayed (for example a primary key while attributes is only content)
  • only_attributes cannot be set to true the way exclude_attributes can, because "show only all attributes" has no meaning. Use attributes: false or exclude_attributes to hide attributes

Grouping models by namespace

Use cluster: true to visually group models by their Ruby namespace. This is especially useful for large applications with many namespaced models.

With Graphviz output, clustering creates subgraph boxes around each namespace:

bundle exec erd --generator=graphviz --cluster=true

With Mermaid classDiagram output, clustering uses Mermaid's native namespace blocks:

bundle exec erd --mermaid_style=classdiagram --cluster=true

This produces output like:

classDiagram
    namespace Admin {
        class User
        class Role
    }
    namespace Billing {
        class Invoice
        class Payment
    }
    User --> Role
    Invoice --> Payment

Note: Clustering is not supported with Mermaid's default erDiagram style (ER diagrams don't have a namespace concept). If you need clustering with Mermaid, use mermaid_style: classdiagram.

You can also customize fonts (useful if the defaults aren't available on your system):

fonts:
  normal: "Arial"
  bold: "Arial Bold"
  italic: "Arial Italic"

Note: The filename option can include a path to output the diagram to a specific directory:

filename: docs/erd

Or via command line:

bundle exec erd --filename="docs/erd"

Mermaid output (default)

Rails ERD generates Mermaid diagrams by default. Mermaid is a text-based diagramming format that renders natively in GitHub, GitLab, Notion, and many other tools.

By default, Mermaid output uses erDiagram syntax with crow's foot notation, PK/FK markers, and proper cardinality. You can switch to classDiagram syntax if preferred:

bundle exec erd --mermaid_style=classdiagram

Or in your .erdconfig:

mermaid_style: classdiagram

The default erDiagram style produces output like:

erDiagram
  User {
    integer id PK
    string name
    integer organization_id FK
  }
  Organization {
    integer id PK
    string name
  }
  Organization ||--o{ User : ""

tbls JSON output

Rails ERD can emit a JSON description of your domain in the tbls schema format. Unlike a schema.rb dump, this output captures the relationships Rails ERD derives from ActiveRecord — so belongs_to associations show up as foreign keys even when the database has no FK constraint.

Any tbls-compatible tool can consume the resulting file. For example, to render an interactive ERD with Liam ERD:

bundle exec erd --generator=tbls
# writes erd.json

npx @liam-hq/cli erd build --input erd.json --format tbls

Graphviz output

For PDF, PNG, or SVG output, you can use the Graphviz generator:

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

This requires:

  • The ruby-graphviz gem in your Gemfile
  • Graphviz installed on your system (brew install graphviz or apt-get install graphviz)

Auto generation

  • Run bundle exec rails g erd:install
  • Run bundle exec rails db:migrate, then the diagram is generated

Using in a gem (without Rails)

If you want to use Rails ERD in a gem that defines ActiveRecord models but doesn't include Rails/Railties, you can use the API directly:

require 'rails_erd/diagram/mermaid'

# Ensure your models are loaded
require_relative 'lib/my_gem/models'

# Generate the diagram
RailsERD::Diagram::Mermaid.create

For Graphviz output:

require 'rails_erd/diagram/graphviz'
RailsERD::Diagram::Graphviz.create

You'll need to ensure your database connection is established and models are loaded before generating the diagram.

Learn more

More information can be found on Rails ERD's project homepage.

If you wish to extend or customise Rails ERD, take a look at the API documentation.

About Rails ERD

Rails ERD was created by Rolf Timmermans (r.timmermans at voormedia.com)

Copyright 2010-2026 Voormedia - www.voormedia.com

License

Rails ERD is released under the MIT license.