rails-erd 1.7.2 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8b58372ac1652af1b21bd00ea88b434bb2d303247eca241f57efd84210bc9367
-  data.tar.gz: aecdcd4cfdb25ed3ef1713da019b456512d2b7bc965ebe0d7acea86e56b4f586
+  metadata.gz: 9dadf622a2d2bcae2e4961d23b1f86647b7eaf4e68ae062dad5a18050b2fc935
+  data.tar.gz: 72115211691f90710ccdfea75c6b8456bae393cc1794b73727006ee3ec7475af
 SHA512:
-  metadata.gz: 1d8c7c596bf41d7753c0c34a468c142021ed66e7b7168dab70f68e57cf587640b5d5c35693b14c4a4c7778cf55b30f5740393454773901720f29c71f16e91c73
-  data.tar.gz: 733fe6e3c637a1f31f750621af09b9803102663b8d5cb611f978c600bc0940856e491a853325f57b4c126cf6e1ec50d55a4d0425ed573f1b722f144333ff4cf9
+  metadata.gz: f19813191fc9a1258053cab237535fb5358e2a804af4bf394bcae0eb1e2b743c1d48c284d100b2044bed76aa57e8f95cd998379e84fc16de9cecbf452d29d816
+  data.tar.gz: b77b4b3e57436b9a32fe92cfec304aa35c8f094fc0c00d615f01c394fae6680f899eab1f548d50986a61534372b48b661d656638502ad1bdad5bc4da3757c139

data/README.md

@@ -6,7 +6,7 @@ Rails ERD - Generate Entity-Relationship Diagrams for Rails applications
 
 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 3.0-5.0. It uses Active Record's built-in reflection capabilities to figure out how your models are associated.
+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
@@ -22,62 +22,158 @@ Browse the [gallery](https://voormedia.github.io/rails-erd/gallery.html) for mor
 Requirements
 ---------------
 
-* Ruby 1.9.3+
-* ActiveRecord 3.x - 5.0.x
+* Ruby 3.1+
+* ActiveRecord 7.0+
+* Graphviz 2.22+ (optional - only needed for PDF/PNG output)
 
 Getting started
 ---------------
 
 See the [installation instructions](https://voormedia.github.io/rails-erd/install.html) for a complete description of how to install Rails ERD. Here's a summary:
 
-* Install Graphviz 2.22+ ([how?](https://voormedia.github.io/rails-erd/install.html)). On macOS with Homebrew run `brew install graphviz`.
-
-* on linux - `sudo apt-get install graphviz`
-
 * Add <tt>gem 'rails-erd', group: :development</tt> to your application's Gemfile
 
 * Run <tt>bundle exec erd</tt>
 
+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?](https://voormedia.github.io/rails-erd/install.html)). 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`). The format of the file is as follows (shown here with the default settings used if no `.erdconfig` is found). More information on [customization options](https://voormedia.github.io/rails-erd/customise.html) can be found in Rails ERD's project documentation.
+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](https://voormedia.github.io/rails-erd/customise.html) can be found in Rails ERD's project documentation.
+
+Here is an example `.erdconfig` showing the default values:
 
 ```yaml
 attributes:
   - content
-  - foreign_keys
-  - inheritance
 disconnected: true
 filename: erd
-filetype: pdf
+filetype: mmd
+generator: mermaid
 indirect: true
 inheritance: false
 markup: true
+mermaid_style: erdiagram
 notation: simple
 orientation: horizontal
 polymorphism: false
 sort: true
 warn: true
-title: sample title
+title: true
 exclude: null
 only: null
 only_recursion_depth: null
 prepend_primary: false
 cluster: false
 splines: spline
+```
+
+You can also customize fonts (useful if the defaults aren't available on your system):
+
+```yaml
 fonts:
- normal: "Arial"
- bold: "Arial Bold"
- italic: "Arial Italic"
+  normal: "Arial"
+  bold: "Arial Bold"
+  italic: "Arial Italic"
+```
+
+**Note:** The `filename` option can include a path to output the diagram to a specific directory:
+
+```yaml
+filename: docs/erd
+```
+
+Or via command line:
+
+```bash
+bundle exec erd filename="docs/erd"
+```
+
+Mermaid output (default)
+------------------------
+
+Rails ERD generates [Mermaid](https://mermaid.js.org/) 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:
+
+```bash
+bundle exec erd mermaid_style=classdiagram
+```
+
+Or in your `.erdconfig`:
+
+```yaml
+mermaid_style: classdiagram
+```
+
+The default `erDiagram` style produces output like:
+
+```mermaid
+erDiagram
+  User {
+    integer id PK
+    string name
+    integer organization_id FK
+  }
+  Organization {
+    integer id PK
+    string name
+  }
+  Organization ||--o{ User : ""
+```
+
+Graphviz output
+---------------
+
+For PDF, PNG, or SVG output, you can use the Graphviz generator:
+
+```bash
+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 <tt>bundle exec rails g erd:install</tt>
 * Run <tt>bundle exec rails db:migrate</tt>, 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:
+
+```ruby
+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:
+
+```ruby
+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
 ----------
 
@@ -91,7 +187,7 @@ About Rails ERD
 
 Rails ERD was created by Rolf Timmermans (r.timmermans *at* voormedia.com)
 
-Copyright 2010-2015 Voormedia - [www.voormedia.com](http://www.voormedia.com/)
+Copyright 2010-2026 Voormedia - [www.voormedia.com](http://www.voormedia.com/)
 
 
 License

data/lib/generators/erd/install_generator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Erd
   module Generators
     class InstallGenerator < Rails::Generators::Base

data/lib/generators/erd/templates/auto_generate_diagram.rake

@@ -1,6 +1,6 @@
 # NOTE: only doing this in development as some production environments (Heroku)
 # NOTE: are sensitive to local FS writes, and besides -- it's just not proper
 # NOTE: to have a dev-mode tool do its thing in production.
-if Rails.env.development?
+if defined? RailsERD
   RailsERD.load_tasks
 end

data/lib/rails-erd.rb

@@ -1 +1,3 @@
+# frozen_string_literal: true
+
 require "rails_erd"

data/lib/rails_erd/cli.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rails_erd"
 require "choice"
 
@@ -5,6 +7,16 @@ Choice.options do
   separator ""
   separator "Diagram options:"
 
+  option :generator do
+    long "--generator=Generator"
+    desc "Generator to use (mermaid or graphviz). Defaults to mermaid."
+  end
+
+  option :mermaid_style do
+    long "--mermaid_style=STYLE"
+    desc "Mermaid diagram style: classdiagram (default) or erdiagram. Only applies when generator is mermaid."
+  end
+
   option :title do
     long "--title=TITLE"
     desc "Replace default diagram title with a custom one."
@@ -12,7 +24,7 @@ Choice.options do
 
   option :notation do
     long "--notation=STYLE"
-    desc "Diagram notation style, one of simple, bachman, uml or crowsfoot."
+    desc "Diagram notation style, one of simple, bachman, uml or crowsfoot (avaiable only with Graphviz engine)."
   end
 
   option :attributes do
@@ -80,6 +92,16 @@ Choice.options do
     desc "Control how edges are represented. See http://www.graphviz.org/doc/info/attrs.html#d:splines for values."
   end
 
+  option :table_names do
+    long "--table_names=BOOLEAN"
+    desc "Label each entity with the table name instead of the ActiveRecord class name."
+  end
+
+  option :native_types do
+    long "--native_types=BOOLEAN"
+    desc "Display the db-native types instead of the Rails migration ones."
+  end
+
   separator ""
   separator "Output options:"
 
@@ -138,16 +160,22 @@ module RailsERD
   class CLI
     attr_reader :path, :options
 
+    # Options that should be converted to symbols
+    SYMBOL_OPTIONS = %i[generator mermaid_style filetype notation orientation].freeze
+
     class << self
       def start
         path = Choice.rest.first || Dir.pwd
         options = Choice.choices.each_with_object({}) do |(key, value), opts|
+          key_sym = key.to_sym
           if key.start_with? "no_"
             opts[key.gsub("no_", "").to_sym] = !value
           elsif value.to_s.include? ","
-            opts[key.to_sym] = value.split(",").map(&:to_s)
+            opts[key_sym] = value.split(",").map(&:to_s)
+          elsif SYMBOL_OPTIONS.include?(key_sym) && value.is_a?(String)
+            opts[key_sym] = value.to_sym
           else
-            opts[key.to_sym] = value
+            opts[key_sym] = value
           end
         end
         if options[:config_file] && options[:config_file] != ''
@@ -159,7 +187,12 @@ module RailsERD
 
     def initialize(path, options)
       @path, @options = path, options
-      require "rails_erd/diagram/graphviz"
+      generator = options[:generator] || RailsERD.options[:generator]
+      if generator == :mermaid
+        require "rails_erd/diagram/mermaid"
+      else
+        require "rails_erd/diagram/graphviz"
+      end
     end
 
     def start
@@ -196,9 +229,18 @@ module RailsERD
     rescue TypeError
     end
 
+    def generator
+      generator_type = options[:generator] || RailsERD.options[:generator]
+      if generator_type == :mermaid
+        RailsERD::Diagram::Mermaid
+      else
+        RailsERD::Diagram::Graphviz
+      end
+    end
+
     def create_diagram
       $stderr.puts "Generating entity-relationship diagram for #{ActiveRecord::Base.descendants.length} models..."
-      file = RailsERD::Diagram::Graphviz.create(options)
+      file = generator.create(options)
       $stderr.puts "Diagram saved to '#{file}'."
       `open #{file}` if options[:open]
     end

data/lib/rails_erd/config.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "yaml"
 
 module RailsERD
@@ -42,7 +44,10 @@ module RailsERD
 
     def load_file(path)
       if File.exist?(path)
-        YAML.load_file(path).each do |key, value|
+        config = YAML.load_file(path)
+        return unless config.is_a?(Hash)
+
+        config.each do |key, value|
           key = key.to_sym
           @options[key] = normalize_value(key, value)
         end
@@ -61,7 +66,7 @@ module RailsERD
         end
 
       # <symbol>
-      when :filetype, :notation
+      when :filetype, :notation, :generator, :mermaid_style
         value.to_sym
 
       # [<string>]

data/lib/rails_erd/diagram/graphviz.rb

@@ -1,19 +1,25 @@
-# encoding: utf-8
+# frozen_string_literal: true
+
 require "rails_erd/diagram"
-require "graphviz"
 require "erb"
 
-# Fix bad RegEx test in Ruby-Graphviz.
-GraphViz::Types::LblString.class_eval do
-  def output # @private :nodoc:
-    if /^<.*>$/m =~ @data
-      @data
-    else
-      @data.to_s.inspect.gsub("\\\\", "\\")
+begin
+  require "graphviz"
+
+  # Fix bad RegEx test in Ruby-Graphviz.
+  GraphViz::Types::LblString.class_eval do
+    def output # @private :nodoc:
+      if /^<.*>$/m =~ @data
+        @data
+      else
+        @data.to_s.inspect.gsub("\\\\", "\\")
+      end
     end
+    alias_method :to_gv, :output
+    alias_method :to_s, :output
   end
-  alias_method :to_gv, :output
-  alias_method :to_s, :output
+rescue LoadError
+  # ruby-graphviz is optional as of v2.0 - only needed when using generator: graphviz
 end
 
 module RailsERD
@@ -123,8 +129,8 @@ module RailsERD
             options[:style] = :dotted if relationship.indirect?
 
             # Cardinality is "look-across".
-            dst = relationship.to_many? ? "crow" : "tee"
-            src = relationship.many_to? ? "crow" : "tee"
+            dst = +(relationship.to_many? ? "crow" : "tee")
+            src = +(relationship.many_to? ? "crow" : "tee")
 
             # Participation is "look-across".
             dst << (relationship.destination_optional? ? "odot" : "tee")
@@ -143,8 +149,8 @@ module RailsERD
             options[:style] = :dotted if relationship.indirect?
 
             # Participation is "look-here".
-            dst = relationship.source_optional? ? "odot" : "dot"
-            src = relationship.destination_optional? ? "odot" : "dot"
+            dst = +(relationship.source_optional? ? "odot" : "dot")
+            src = +(relationship.destination_optional? ? "odot" : "dot")
 
             # Cardinality is "look-across".
             dst << "normal" if relationship.to_many?
@@ -181,6 +187,11 @@ module RailsERD
       attr_accessor :graph
 
       setup do
+        unless defined?(GraphViz)
+          raise LoadError, "The ruby-graphviz gem is required for Graphviz output. " \
+            "Add `gem 'ruby-graphviz'` to your Gemfile, or use `generator: mermaid` instead."
+        end
+
         self.graph = GraphViz.digraph(domain.name)
 
         # Set all default attributes.
@@ -238,6 +249,8 @@ module RailsERD
 
       each_relationship do |relationship|
         from, to = relationship.source, relationship.destination
+        next unless from && to
+
         unless draw_edge from.name, to.name, relationship_options(relationship)
           from.children.each do |child|
             draw_edge child.name, to.name, relationship_options(relationship)

data/lib/rails_erd/diagram/mermaid.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+require "rails_erd/diagram"
+require "erb"
+
+module RailsERD
+  class Diagram
+    class Mermaid < Diagram
+
+      attr_accessor :graph
+
+      setup do
+        self.graph = [diagram_type]
+
+        # Respect orientation option: horizontal = TB (top-down), vertical = LR (left-right)
+        direction = (options.orientation.to_s == "vertical") ? "LR" : "TB"
+        self.graph << "\tdirection #{direction}"
+      end
+
+      each_entity do |entity, attributes|
+        if er_diagram?
+          # Build entity block as a single string to avoid uniq issues with closing braces
+          entity_lines = ["\t#{entity} {"]
+          attributes.each do |attr|
+            key_marker = attribute_key_marker(attr)
+            entity_lines << "\t\t#{attr.type} #{attr.name}#{key_marker}"
+          end
+          entity_lines << "\t}"
+          graph << entity_lines.join("\n")
+        else
+          graph << "\tclass `#{entity}`"
+          attributes.each do |attr|
+            graph << "\t`#{entity}` : +#{attr.type} #{attr.name}"
+          end
+        end
+      end
+
+      each_specialization do |specialization|
+        from, to = specialization.generalized, specialization.specialized
+        if er_diagram?
+          # erDiagram doesn't have a direct polymorphic notation, use inheritance-like
+          graph << "\t#{from.name} ||--o{ #{to.name} : \"specializes\""
+        else
+          graph << "\t<<polymorphic>> `#{specialization.generalized}`"
+          graph << "\t #{from.name} <|-- #{to.name}"
+        end
+      end
+
+      each_relationship do |relationship|
+        from, to = relationship.source, relationship.destination
+        next unless from && to
+
+        if er_diagram?
+          graph << "\t#{from.name} #{er_relation_notation(relationship)} #{to.name} : \"\""
+
+          from.children.each do |child|
+            graph << "\t#{child.name} #{er_relation_notation(relationship)} #{to.name} : \"\""
+          end
+
+          to.children.each do |child|
+            graph << "\t#{from.name} #{er_relation_notation(relationship)} #{child.name} : \"\""
+          end
+        else
+          graph << "\t`#{from.name}` #{relation_arrow(relationship)} `#{to.name}`"
+
+          from.children.each do |child|
+            graph << "\t`#{child.name}` #{relation_arrow(relationship)} `#{to.name}`"
+          end
+
+          to.children.each do |child|
+            graph << "\t`#{from.name}` #{relation_arrow(relationship)} `#{child.name}`"
+          end
+        end
+      end
+
+      save do
+        raise "Saving diagram failed!\nOutput directory '#{File.dirname(filename)}' does not exist." unless File.directory?(File.dirname(filename))
+
+        File.write(filename.gsub(/\s/,"_"), graph.uniq.join("\n"))
+        filename
+      end
+
+      def filename
+        "#{options.filename}.mmd"
+      end
+
+      def diagram_type
+        er_diagram? ? "erDiagram" : "classDiagram"
+      end
+
+      def er_diagram?
+        options[:mermaid_style] == :erdiagram || options[:mermaid_style] == :er
+      end
+
+      # erDiagram relationship notation using crow's foot
+      # Format: left_cardinality--right_cardinality
+      # Cardinality markers:
+      #   || = exactly one
+      #   o| = zero or one
+      #   }| = one or more
+      #   }o = zero or more
+      def er_relation_notation(relationship)
+        line = relationship.indirect? ? ".." : "--"
+
+        # Left side (source cardinality - how many source entities relate to one destination)
+        left = if relationship.many_to?
+          relationship.source_optional? ? "o{" : "|{"
+        else
+          relationship.source_optional? ? "o|" : "||"
+        end
+
+        # Right side (destination cardinality - how many destination entities relate to one source)
+        right = if relationship.to_many?
+          relationship.destination_optional? ? "}o" : "}|"
+        else
+          relationship.destination_optional? ? "|o" : "||"
+        end
+
+        "#{left}#{line}#{right}"
+      end
+
+      def attribute_key_marker(attr)
+        markers = []
+        markers << "PK" if attr.primary_key?
+        markers << "FK" if attr.foreign_key?
+        markers.empty? ? "" : " #{markers.join(',')}"
+      end
+
+      # classDiagram relationship arrows (legacy)
+      def relation_arrow(relationship)
+        arrow_body = arrow_body relationship
+        arrow_head = arrow_head relationship
+        arrow_tail = arrow_tail relationship
+
+        "#{arrow_tail}#{arrow_body}#{arrow_head}"
+      end
+
+      def arrow_body(relationship)
+        relationship.indirect? ? ".." : "--"
+      end
+
+      def arrow_head(relationship)
+        relationship.to_many? ?  ">" : ""
+      end
+
+      def arrow_tail(relationship)
+        relationship.many_to? ? "<" : ""
+      end
+
+    end
+  end
+end

data/lib/rails_erd/diagram/templates/node.html.erb

@@ -1,6 +1,6 @@
 <% if options.orientation == :horizontal %>{<% end %>
 <table border="0" align="center" cellspacing="0.5" cellpadding="0" width="<%= NODE_WIDTH + 4 %>">
-  <tr><td align="center" valign="bottom" width="<%= NODE_WIDTH %>"><font face="<%= FONTS[:bold] %>" point-size="11"><%= entity.name %></font></td></tr>
+  <tr><td align="center" valign="bottom" width="<%= NODE_WIDTH %>"><font face="<%= FONTS[:bold] %>" point-size="11"><%= entity.label %></font></td></tr>
 </table>
 <% if attributes.any? %>
 |

data/lib/rails_erd/diagram/templates/node.record.erb

@@ -1,4 +1,4 @@
-<% if options.orientation == :horizontal %>{<% end %><%= entity.name %><% if attributes.any? %>
+<% if options.orientation == :horizontal %>{<% end %><%= entity.label %><% if attributes.any? %>
 |<%  attributes.each do |attribute| %><%=
        attribute %> (<%= attribute.type_description %>)
-<%   end %><% end %><% if options.orientation == :horizontal %>}<% end %>
+<%   end %><% end %><% if options.orientation == :horizontal %>}<% end %>

data/lib/rails_erd/diagram.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "rails_erd/domain"
 
 module RailsERD
@@ -126,8 +128,10 @@ module RailsERD
       instance_eval(&callbacks[:setup])
       if options.only_recursion_depth.present?
         depth = options.only_recursion_depth.to_s.to_i
+        # Ensure options[:only] is an array (CLI may pass a single string)
+        options[:only] = [options[:only]].flatten
         options[:only].dup.each do |class_name|
-          options[:only]+= recurse_into_relationships(@domain.entity_by_name(class_name), depth)
+          options[:only] += recurse_into_relationships(@domain.entity_by_name(class_name), depth)
         end
         options[:only].uniq!
       end

data/lib/rails_erd/domain/attribute.rb

@@ -1,4 +1,4 @@
-# encoding: utf-8
+# frozen_string_literal: true
 
 #--
 module RailsERD
@@ -49,7 +49,7 @@ module RailsERD
       # The type of the attribute, equal to the Rails migration type. Can be any
       # of +:string+, +:integer+, +:boolean+, +:text+, etc.
       def type
-        column.type or column.sql_type.downcase.to_sym
+        !RailsERD.options[:native_types] and column.type or column.sql_type.downcase.to_sym
       end
 
       # Returns +true+ if this attribute is a content column, that is, if it
@@ -77,9 +77,18 @@ module RailsERD
       # Returns +true+ if this attribute is used as a foreign key for any
       # relationship.
       def foreign_key?
-        @domain.relationships_by_entity_name(@model.name).map(&:associations).flatten.map { |associaton|
-          associaton.send(Domain.foreign_key_method_name).to_sym
-        }.include?(name.to_sym)
+        @domain
+          .relationships_by_entity_name(@model.name)
+          .map(&:associations)
+          .flatten
+          .map do |associaton|
+            result = associaton.send(Domain.foreign_key_method_name)
+            if result.respond_to?(:to_ary)
+              result.join("_").to_sym
+            else
+              result.to_sym
+            end
+          end.include?(name.to_sym)
       end
 
       # Returns +true+ if this attribute is used for single table inheritance.
@@ -120,6 +129,7 @@ module RailsERD
       # <tt>:boolean, :null => false</tt>:: boolean *
       def type_description
         type.to_s.dup.tap do |desc|
+          desc << "[]" if column.respond_to?(:array?) && column.array?
           desc << " #{limit_description}" if limit_description
           desc << " ∗" if mandatory? && !primary_key? # Add a hair space + low asterisk (Unicode characters)
           desc << " U" if unique? && !primary_key? && !foreign_key? # Add U if unique but non-key