rails-erd 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4d47dd705b783be29e06d39d8bea92d6c5ac8019fba658e0279287b2197938d3
-  data.tar.gz: 1417646a7d2731ad2964e9cbac400cb3b2325f765ba1db610b44f28ffe03f699
+  metadata.gz: 07a38b05691f97bf85079684c7412bff0bf8b4caf737f52479d2209b3fb2fe5f
+  data.tar.gz: c8f38108442a38b331cff3b2c0b856584943ac3def5cec0525255c53595e0482
 SHA512:
-  metadata.gz: cde6a9b96a0d3e5c03ccbed1c3e04e37d27efb3a37d2a09e1a5ff298cbb4e9ec3148065c551efe8da349315d7601420b3b98bccf049f4c83b782863a6a13f495
-  data.tar.gz: 5d53400f939b341b02becb90a5b4b413d4556a0fc36ef856d4c831d13ccc343ab0fd48772c8245ebedcdcdfee028068d51b1a09027ae809614c568bf19506505
+  metadata.gz: 146e37a81b1f2008f28442f62498822845810a45bb9a5ab1ba35fec8700be809ba2eac95be388a15878e9ff44d7dc5b4abd8b4db8b479871a993a93668d75337
+  data.tar.gz: 9e5d0c84231120c3e1b804950265a3a6abca1201f46f99bd96b3a0655e46c13bdbb0e7ff0403902f621506de81240818cc7135f92423f8a1be0e50c2468629d2

data/CHANGES.md

@@ -0,0 +1,335 @@
+2.1.0
+-----
+
+### New Features
+* Add `cluster: true` support for Mermaid `classDiagram` output, grouping entities by Ruby namespace into Mermaid `namespace { }` blocks (#479, #480)
+* Add glob and regex pattern support for `exclude` and `only` options, allowing entire namespaces to be filtered with patterns like `"SolidQueue::*"` or `"/^Active/"` (#465, #478)
+* Add tbls JSON generator for integration with Liam ERD and other tbls-compatible tools (#471, #474)
+
+### Bug Fixes
+* Invalid generator option now falls back to mermaid (the documented default) instead of graphviz
+* Fix unparseable Mermaid output when `polymorphism` is enabled and an abstract parent has a tableless child (#459, #463)
+* Fix `only`/`exclude` not filtering relationships, so filtered-out models no longer leak back into Mermaid diagrams as phantom nodes (#472, #473)
+* Process models in a stable order so relationship order and source/destination direction are deterministic across runs, avoiding churn in generated diagrams committed to version control (#475, #476)
+
+### Internal
+* Restructure `filtered_attributes` for readability and add edge-case tests for `exclude_attributes` normalization (#458)
+* Fix README to show the correct command-line flag syntax for ERD generator options (#461)
+* Add a native Mermaid preview diagram to the README (#466)
+* Fix stale `LICENSE`/`CHANGES.rdoc` references in the YARD task and gemspec so the license and changelog are documented and packaged (#469)
+* Update LICENSE copyright year to 2026 (#468)
+
+2.0.2
+-----
+
+### Features
+* Add `exclude_attributes` option to hide attributes on a per-model basis (#421, #457)
+
+### Bug Fixes
+* Fix crash when using `exclude` option with polymorphic associations on Rails 8 (#454, #455, #456)
+
+2.0.1
+-----
+
+### Bug Fixes
+* Fix mermaid syntax errors for namespaced class names (#450, #451)
+* Fix test helper to correctly create namespaced models (#451)
+
+### Internal
+* Use temp directory for test output files (#453)
+
+2.0.0
+-----
+
+### Breaking Changes
+* Default generator changed from Graphviz to Mermaid (#448)
+* Default filetype changed from PDF to MMD (#448)
+* Default mermaid_style changed from classDiagram to erDiagram (#448)
+* Default direction changed from RL to TB (top-down) (#448)
+* ruby-graphviz gem is now optional (#448)
+
+### New Features
+* Mermaid erDiagram style with crow's foot notation and PK/FK markers (#445)
+* CLI now supports all options that rake task supports (#446, #447)
+* Mermaid direction respects orientation option (#448)
+
+### Bug Fixes
+* Fix --only flag with single model (#441)
+* Fix nil destination crash (#440)
+* Fix empty .erdconfig crash (#443)
+* Fix CLI string-to-symbol option conversion (#447)
+* Exclude Rails 8 Solid* internal models (#437, #438, #439)
+* Suppress Ruby 3.4 hash key warnings (#436)
+
+### Documentation
+* Updated README for Mermaid as default (#444, #448)
+* Added non-Rails usage example (#444)
+
+1.7.2
+-----
+* Suppress warnings for tableless Rails models (#390)
+* Fix example erdconfig foreign keys (docs) (#392)
+* Replace CI badge from Travis to GH Actions (#393)
+* Fix spelling error in error msg (#394)
+* Handle deprecated direct_descendants (#395)
+* Map foreign keys & current column name to symbols (#397)
+
+1.7.1
+-----
+* Fix for frozen string error (#382)
+* Updated graphviz docs for linux (#351)
+
+1.7.0
+-----
+* Added support for Rails 7.0 and Ruby 3.0 (#379)
+* Added optional configuration to set which fonts to use (#378)
+* Improvements to rake tasks (#333, #373)
+* Made loading environment.rb optional (#371)
+
+
+1.6.1
+-----
+* Added support for Rails 6.1 (#365)
+
+1.6.0
+-----
+* Dropping support for Ruby < 2.2 and Rails < 4.2 (#323)
+* Added early support for Rails 6.0 (#329)
+* Documentation updates (#268, #269, #276, #288, #295)
+* Removed restriction that allowed to exclude only models from a diagram (#279)
+* Added additional margins to cluster (#280)
+* Deprecate safe_level of ERB.new in Ruby 2.6 (#297)
+* Fixed only_recursion_depth option failure when used from rake erd task (#266, #324)
+* Allow extra config files to be listed via cli (#275, #326)
+* Fixed long-standing segfault issue by removing identifier from association_identity (#296, #327)
+* Fix for bug when parameter to only option is a single model (#300, #328)
+* Properly handle custom version classes. (#304, #325)
+* Fixed a warning from Ruby RE ambiguous arguments (#315)
+* Updated gem dependencies (#311, #313)
+
+1.5.2
+-----
+* Disable calls to `eager_load_namespaces` < Rails 5 (#263)
+
+1.5.1
+-----
+
+* Improved < Ruby 2.3 support (#239)
+* Squashed once and for all the horizontal vs vertical orientation bugs (#241)
+* Added option for specifying spline types (#242)
+* Added a check for Graphviz installation before building out object graph (#248)
+* Fixed a bug in auto-generation rake task (#252)
+* `--cluster` option will work more reliably now! (#253)
+* Because it is 2017, we added Rails 5 to our official test matrix (#254)
+* Fixed a bug in `--only` that prevented it from working reliably (#257)
+* Added eager loading across all namespaces in the app (#258)
+* Minor improvements to tests (#228)
+
+1.5.0
+-----
+* New option of 'clustering' by namespace (#205)
+* Support for 'only_models_include_depth' option (#219)
+* Added basic support for non-Rails apps (#208)
+* Avoid duplicate specializations when using STI with an abstract base class (#211)
+* Fixed Ruby 2.1 deprecation warnings (#209)
+* Fixes to tests (#210, #213)
+* Various documentation fixes (#203, #212)
+
+1.4.7
+-----
+* Fixed grouping of associations (#190)
+* Fixed issue with command line options (#198)
+* Fixed horizontally graph when vertical was wanted and viceversa (#183)
+
+1.4.6
+-----
+* Revert auto-generation of diagrams added in #176 (#191)
+* Fix some Ruby warnings (#187)
+* Rescue from TypeError when loading target app (#185)
+
+1.4.5
+-----
+
+* Fix bug in `auto generate diagram` (#176)
+* Protect against `nil` model names (#177, #178)
+
+1.4.4
+-----
+
+* Return nil if native_type is geography (#168)
+* Change tests to address flickering failures on Travis-CI
+
+1.4.3
+-----
+
+* Fix for bug where defaults were overriding configuration options (#166)
+
+1.4.2
+-----
+
+* Fix for issue with strings vs symbols in options (#157)
+* Fix for 'geometry' columns causing errors (#158)
+
+1.4.1
+-----
+
+* Improved travis-ci testing
+* Improved speed of Attribute#from_model (#145)
+* Fixed a long-standing bug in rake task (#149)
+* Fixed 'No entities found' error when using filter (#152)
+* Prevent deprecation warning by specifying test order (#153)
+* Updated CODE_OF_CONDUCT
+
+1.4.0
+-----
+
+* Drop support for spaces in filenames (#123)
+* Ensure that #generalized? could be used (#127)
+* Fixing typos in font config (#140)
+
+1.3.1
+-----
+
+* Check that models are not abstract (#47)
+* Added MIT license (#117)
+* Fixed an issue with :only and :exclude options (#122)
+* Added a :sort option to preserve original attribute order (#126)
+* Mark primary and unique keys as such in diagram (#129)
+
+1.3.0
+-----
+
+* Added support for Rails 4 (Issues #120, #115, #85, #89, and #68)
+
+1.2.2
+-----
+
+* Fixes a bug in sorting abstract classes (Issues #54, #88)
+
+1.2.1
+-----
+
+* Fixes a bug in OS detection for JRuby (and newer MRI Rubies, too)
+
+1.2.0
+-----
+
+* Fixed bug that prevented generation of diagrams on newer versions of OSX
+* Added ability to store CLI configuration options in a config file, both a global version (in the user's home directory) as well as a per-project local versions
+* Added a Code of Conduct for the project
+
+1.1.0
+-----
+
+* Abstract models (with 'self.abstract_class = true') are now considered for
+  the domain and will be displayed if 'polymorphism=true'. This should also
+  fix errors that could occur if abstract models had any associations.
+* Correctly save Graphviz diagrams with spaces in the filename (contributed by
+  Neil Chambers).
+* Add only/exclude to CLI (contributed by Dru Ibarra).
+
+
+1.0.0
+-----
+
+* The internal API is now stable and will be backwards compatible until
+  the next major version.
+* Added experimental command line interface (erd). The CLI still requires a
+  Rails application to be present, but it may one day support other kinds of
+  applications.
+* Crow's foot notation (also known as the Information Engineering notation)
+  can be used by adding 'notation=crowsfoot' to the 'rake erd' command
+  (contributed by Jeremy Holland).
+* Filter models by using the only or exclude options (only=ModelOne,ModelTwo
+  or exclude=ModelThree,ModelFour) from the command line (contributed by
+  Milovan Zogovic).
+* Process column types that are unsupported by Rails (contributed by Erik
+  Gustavson).
+* Ignore custom limit/scale attributes that cannot be converted to an integer
+  (reported by Adam St. John).
+
+0.4.5
+-----
+
+* Display more helpful error message when the application models could not be
+  loaded successfully by the 'rake erd' task (reported by Greg Weber).
+
+0.4.4
+-----
+
+* Added the ability to disable HTML markup in node labels (markup=false). This
+  causes .dot files to be compatible with OmniGraffle, which otherwise fails
+  to import graphs with HTML node labels (issue reported by Lucas Florio,
+  implementation based on template by Troy Anderson).
+* Prevent models named after Graphviz reserved words (Node, Edge) from causing
+  errors in .dot files (reported by gguthrie).
+* Improved error messages when Graphviz is throwing errors (reported by
+  Michael Irwin).
+
+0.4.3
+-----
+
+* Display the scale of decimal attributes when set. A decimal attribute with
+  precision 5 and scale 2 is now indicated with (5,2).
+* Fixed deprecation warnings for edge Rails (upcoming 3.1).
+
+0.4.1
+-----
+
+* Fix processing of associations with class_name set to absolute module paths.
+* Adjust model loading process to include models in non-standard paths eagerly.
+
+0.4.0
+-----
+
+* Support to optionally display single table inheritance relationships
+  (inheritance=true).
+* Support to optionally display polymorphic associations (polymorphism=true).
+* Adjustments to 'advanced' style so that it matches original Bachman style,
+  and therefore now called 'bachman'.
+* Ignore models without tables (reported by Mark Chapman).
+* Mutual indirect relationships are now combined.
+* Changed API for diagram generation.
+* Restructured classes and renamed several API properties and methods.
+* Added new edge type to describe single table inheritance and polymorphic
+  associations: Specialization.
+* Added compatibility for Active Record 3.1 (beta), removed dependency on Arel.
+* Rubinius compatibility.
+
+0.3.0
+-----
+
+* Added the ability to support multiple styles of cardinality notations.
+  Currently supported types are 'simple' and 'advanced'.
+* Added option to exclude indirect relationships (indirect=false).
+* Added option to change or disable the diagram title (title='Custom title').
+* Altered the type descriptions of attributes.
+* Renamed options for flexibility and clarity.
+* Improved internal logic to determine the cardinality of relationships.
+* More versatile API that allows you to inspect relationships and their
+  cardinalities.
+* Changed line widths to 1.0 to avoid invisible node boundaries with older
+  versions of Graphviz (reported by Mike McQuinn).
+* Bundled examples based on actual applications.
+
+0.2.0
+-----
+
+* Added simple way to create your own type of diagrams with a tiny amount of code.
+* Improved internal API and documentation.
+* Subtle changes in diagram style.
+* Fixed error where non-mutual relationships might be inadvertently classified
+  as indirect relationships.
+* Fixed error where diagrams with a vertical layout might fail to be generated.
+
+0.1.1
+-----
+
+* Fixed small errors in Ruby 1.8.7.
+* Abort generation of diagrams when there are no models.
+
+0.1.0
+-----
+
+* Released on September 20th, 2010.
+* First public release.

data/LICENSE.md

@@ -0,0 +1,19 @@
+Copyright (c) 2010-2026 Voormedia B.V.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -12,7 +12,86 @@ Rails ERD was created specifically for Rails and works on versions 6.0 and later
 Preview
 -------
 
-Here's an example entity-relationship diagram that was generated by Rails ERD:
+Since version 2.0, Rails ERD generates [Mermaid](https://mermaid.js.org/) 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):
+
+```mermaid
+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](https://voormedia.github.io/rails-erd/images/entity-relationship-diagram.png)
 
@@ -43,7 +122,7 @@ This generates a Mermaid diagram (`erd.mmd`) by default. Mermaid diagrams render
 
 * Add `gem 'ruby-graphviz'` to your Gemfile
 
-* Run `bundle exec erd generator=graphviz filetype=pdf`
+* Run `bundle exec erd --generator=graphviz --filetype=pdf`
 
 ### Configuration
 
@@ -104,6 +183,96 @@ bundle exec rake erd exclude_attributes="BigTable,User.password_digest,User.reme
 bundle exec erd --exclude_attributes="BigTable,User.password_digest,User.remember_token"
 ```
 
+### 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):
+
+```yaml
+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:
+
+```yaml
+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:
+
+```yaml
+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:
+
+```yaml
+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`
+
+### 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:
+
+```bash
+bundle exec erd --generator=graphviz --cluster=true
+```
+
+**With Mermaid `classDiagram` output**, clustering uses Mermaid's native namespace blocks:
+
+```bash
+bundle exec erd --mermaid_style=classdiagram --cluster=true
+```
+
+This produces output like:
+
+```mermaid
+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):
 
 ```yaml
@@ -122,7 +291,7 @@ filename: docs/erd
 Or via command line:
 
 ```bash
-bundle exec erd filename="docs/erd"
+bundle exec erd --filename="docs/erd"
 ```
 
 Mermaid output (default)
@@ -133,7 +302,7 @@ Rails ERD generates [Mermaid](https://mermaid.js.org/) diagrams by default. Merm
 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
+bundle exec erd --mermaid_style=classdiagram
 ```
 
 Or in your `.erdconfig`:
@@ -158,13 +327,32 @@ erDiagram
   Organization ||--o{ User : ""
 ```
 
+tbls JSON output
+----------------
+
+Rails ERD can emit a JSON description of your domain in the
+[tbls](https://github.com/k1LoW/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](https://liambx.com):
+
+```bash
+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:
 
 ```bash
-bundle exec erd generator=graphviz filetype=pdf
+bundle exec erd --generator=graphviz --filetype=pdf
 ```
 
 This requires:

data/Rakefile

@@ -9,7 +9,7 @@ Rake::TestTask.new do |test|
 end
 
 YARD::Rake::YardocTask.new do |yard|
-  yard.files = ["lib/**/*.rb", "-", "LICENSE", "CHANGES.md"]
+  yard.files = ["lib/**/*.rb", "-", "LICENSE.md", "CHANGES.md"]
 end
 
 desc "Generate diagrams for bundled examples"

data/lib/rails_erd/cli.rb

@@ -9,7 +9,7 @@ Choice.options do
 
   option :generator do
     long "--generator=Generator"
-    desc "Generator to use (mermaid or graphviz). Defaults to mermaid."
+    desc "Generator to use (mermaid, graphviz, or tbls). Defaults to mermaid."
   end
 
   option :mermaid_style do
@@ -193,10 +193,11 @@ module RailsERD
     def initialize(path, options)
       @path, @options = path, options
       generator = options[:generator] || RailsERD.options[:generator]
-      if generator == :mermaid
-        require "rails_erd/diagram/mermaid"
-      else
-        require "rails_erd/diagram/graphviz"
+      case generator
+      when :mermaid  then require "rails_erd/diagram/mermaid"
+      when :tbls     then require "rails_erd/diagram/tbls"
+      when :graphviz then require "rails_erd/diagram/graphviz"
+      else                require "rails_erd/diagram/mermaid"
       end
     end
 
@@ -236,10 +237,11 @@ module RailsERD
 
     def generator
       generator_type = options[:generator] || RailsERD.options[:generator]
-      if generator_type == :mermaid
-        RailsERD::Diagram::Mermaid
-      else
-        RailsERD::Diagram::Graphviz
+      case generator_type
+      when :mermaid  then RailsERD::Diagram::Mermaid
+      when :tbls     then RailsERD::Diagram::Tbls
+      when :graphviz then RailsERD::Diagram::Graphviz
+      else                RailsERD::Diagram::Mermaid
       end
     end