Generate Mermaid-compatible Entity Relationship Diagrams (ERDs) from your Rails models, with support for excluding specific models. Designed for modern Rails apps that use Active Record.
Keeping ER diagrams up to date is usually manual, and they quickly go stale. This gem generates a diagram directly from your Rails models, so your documentation always reflects the current domain model with almost no effort.
- Outputs a Mermaid
erDiagramtodocumentation/domain-model.md - Includes all Active Record models with a database table
- Excludes models listed in
config/mermaid_erd.ymlunderexclude - Visualises
belongs_toassociations - Run via a Rake task (
rake erd:generate) - Adds a post-migration reminder in development
- Ruby 3.4+
- Rails 8+
- PostgreSQL (uses array/enum column support)
Add this line to the development section of your Gemfile:
gem "mermaid_erd"Then install:
bundle installAlternatively, install it directly:
gem install mermaid_erdRun the following Rake task to generate the ERD:
bundle exec rake erd:generateThis will output a Mermaid diagram to:
documentation/domain-model.md
You can customize which models to exclude by creating a file at:
# config/mermaid_erd.yml
exclude:
- ActiveStorage::*
- SolidQueue::*
- Blazer::*You can limit to specific models:
# config/mermaid_erd.yml
only:
- Order
- Customer
- ProductTo remind developers to regenerate the diagram after each migration, this gem automatically hooks into db:migrate and prints a message like:
[ℹ] If this migration added or modified database tables, consider:
• Updating the Mermaid ER diagram: bundle exec rake erd:generate
• Excluding models in: config/mermaid_erd.yml
⚠ This task only runs in the development environment.
Example output (documentation/domain-model.md):
erDiagram
Saiyan {
integer id
string name
enum rank
integer power_level
boolean tail
datetime born_at
datetime created_at
datetime updated_at
}
Planet {
integer id
string name
boolean destroyed
datetime created_at
datetime updated_at
}
Transformation {
integer id
integer saiyan_id
enum form
integer power_multiplier
datetime achieved_at
datetime created_at
datetime updated_at
}
Battle {
integer id
string location
enum outcome
datetime started_at
datetime finished_at
datetime created_at
datetime updated_at
}
BattleParticipation {
integer id
integer battle_id
integer fighter_id
enum fighter_type
integer damage_dealt
boolean defeated
datetime created_at
datetime updated_at
}
Sensei {
integer id
string name
string technique_speciality
datetime created_at
datetime updated_at
}
TrainingSession {
integer id
integer saiyan_id
integer sensei_id
integer planet_id
integer duration_days
integer power_gained
datetime started_at
datetime finished_at
datetime created_at
datetime updated_at
}
Saiyan }o--|| Planet : belongs_to
Transformation }o--|| Saiyan : belongs_to
TrainingSession }o--|| Saiyan : belongs_to
TrainingSession }o--|| Sensei : belongs_to
TrainingSession }o--|| Planet : belongs_to
BattleParticipation }o--|| Battle : belongs_to
BattleParticipation }o--|| Saiyan : belongs_to