BlastRadius

A Ruby gem for visualizing the cascade deletion impact in Rails applications. BlastRadius helps you understand which records will be deleted when you delete a record, based on ActiveRecord associations with dependent options.

• Dependency Analysis: Analyze ActiveRecord model associations and their dependent options
• Cascade Visualization: Build and visualize dependency trees showing cascade deletion paths
• Impact Calculation: Calculate the actual number of records that would be deleted
• Multiple Dependent Types: Support for :destroy, :delete_all, :destroy_async, :nullify, :restrict_with_exception, :restrict_with_error
• Multiple Output Formats:
  • Text: ASCII tree for terminal/console
  • Mermaid: Diagrams for Markdown (GitHub, GitLab)
  • JSON: Machine-readable format for APIs
  • DOT: Graphviz format for generating images (PNG, SVG, PDF)
  • HTML: Self-contained interactive visualization
• Rails Integration: ActiveRecord DSL, Rake tasks, and console helpers
• Configurable: Depth limits, model exclusion patterns, and format options
• Safe: Dry-run mode to preview deletions without actually deleting

Add this line to your application's Gemfile:

gem 'blast_radius'

And then execute:

bundle install

# Analyze a model
tree = BlastRadius.analyze(User)

# Format as text
formatter = BlastRadius::Formatters::TextFormatter.new
puts formatter.format(tree)

# Class method - analyze model dependencies
User.blast_radius                      # Default format (text)
User.blast_radius(format: :mermaid)    # Mermaid format
User.blast_radius(format: :json)       # JSON format
User.blast_radius(format: :dot)        # DOT (Graphviz) format
User.blast_radius(format: :html)       # HTML format

# Instance methods - analyze specific record impact
user = User.find(1)
user.blast_radius_impact               # Returns hash of model => count
user.blast_radius_dry_run              # Returns detailed impact with sample IDs

# Visualize all models
rails blast_radius:visualize

# Visualize specific model
rails blast_radius:visualize[User]

# Visualize with different format
rails blast_radius:visualize[User,mermaid]
FORMAT=json rails blast_radius:visualize[User]

# Calculate impact of deleting a specific record
rails blast_radius:impact[User,123]

# Generate HTML file
rails blast_radius:html[User,output.html]

Calculate the actual number of records that would be deleted:

user = User.find(1)

# Simple count
impact = user.blast_radius_impact
# => {"Post" => 5, "Comment" => 20, "Like" => 100}

# Detailed information with sample IDs
detailed = user.blast_radius_dry_run
# => {
#   "Post" => {
#     count: 5,
#     dependent_type: :destroy,
#     sample_ids: [1, 2, 3, 4, 5]
#   },
#   "Comment" => {...}
# }

# config/initializers/blast_radius.rb
BlastRadius.configure do |config|
  config.max_depth = 10
  config.default_format = :text
  config.include_nullify = false
  config.include_restrict = false
  config.exclude_models = [/^HABTM_/, /^ActiveStorage::/]
  config.colorize = true
end

BlastRadius supports multiple output formats for different use cases. See the examples/ directory for complete examples.

Terminal-friendly output with box-drawing characters:

User
├── [destroy] posts (Post)
│   ├── [destroy] comments (Comment)
│   │   └── [destroy] reactions (Reaction)
│   └── [delete_all] likes (Like)
├── [destroy] profile (Profile)
└── [destroy_async] notifications (Notification)

For documentation in Markdown (GitHub, GitLab):

graph TD
    User -->|posts|destroy| node1[Post]
    node1 -->|comments|destroy| node2[Comment]
    node2 -->|reactions|destroy| node3[Reaction]
    node1 -->|likes|delete_all| node4[Like]
    User -->|profile|destroy| node5[Profile]
    User -->|notifications|destroy_async| node6[Notification]

For programmatic processing:

{
  "model": "User",
  "children": [
    {
      "model": "Post",
      "association": "posts",
      "type": "has_many",
      "dependent": "destroy",
      "children": [
        {
          "model": "Comment",
          "association": "comments",
          "type": "has_many",
          "dependent": "destroy"
        }
      ]
    }
  ]
}

Generate PNG/SVG/PDF diagrams:

User.blast_radius(format: :dot) # => DOT format output
# Save and convert:
# dot -Tpng output.dot -o diagram.png

The HTML formatter generates a professional, interactive Entity-Relationship diagram with cascade deletion heatmap:

# Generate interactive HTML
html = User.blast_radius(format: :html)
File.write('blast_radius.html', html)

# Open in browser to see:
# - Full ER diagram of all models
# - Click any model to see cascade deletion impact
# - Color-coded heatmap (red → orange → yellow by depth)
# - Multiple layout algorithms (Force, Tree)
# - Zoom, pan, and export capabilities

Core Features:

• Heatmap Visualization: Click on any table to see which other tables will be affected when deleting records
• Depth-Based Coloring:
  • 🔴 Red: Directly deleted (depth 1)
  • 🟠 Orange: Indirectly deleted (depth 2)
  • 🟡 Yellow: Further cascades (depth 3+)
  • ⬜ Gray: Unaffected tables

Layout Algorithms:

• ⚡ Force: Physics-based automatic layout (default)
• 🌳 Tree: Hierarchical top-down view from selected model

Interaction:

• Mouse Wheel: Zoom in/out
• Drag Background: Pan across the graph
• Click Node: Select and see cascade impact
• Hover: Tooltips with model and association details
• Fit to Screen: Auto-zoom to show all nodes

Export:

• SVG: Vector format for editing
• PNG: Raster format for presentations

Keyboard Shortcuts:

• Escape: Reset selection
• F: Fit to screen
• +/-: Zoom in/out

Technical:

• No External Dependencies: Completely self-contained HTML file
• Dark Mode: Automatically adapts to OS preference
• Responsive Design: Works on desktop and mobile
• Console Access: window.blastRadiusGraph for programmatic control

See the examples/ directory for complete output samples.

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests.

• Ruby >= 3.0.0
• Rails >= 6.1 (ActiveRecord)

The gem is available as open source under the terms of the MIT License.

Bug reports and pull requests are welcome on GitHub.