CanvasERD

CanvasERD is a companion gem for editing diagrams generated from Rails ERD domain models in a local browser.

The editor renders Rails models and relationships on an interactive Fabric.js canvas. New diagrams use ELK's layered graph layout to arrange tables from their Rails relationships.

Add CanvasERD to the development group in the Rails application's Gemfile:

group :development do
  gem "canvas_erd", require: false
end

Then run bundle install. CanvasERD requires Ruby 3.1 or newer, Active Record 7.0 or newer, and a Rack server available in the Rails bundle.

From a Rails application root, run:

bundle exec canvas_erd

CanvasERD loads and eager-loads the Rails application, generates the schema, starts on a loopback-only address, and opens the editor in the default browser. Pass --no-open to print the URL without opening it.

CanvasERD uses Rackup with a server handler already present in the Rails bundle, normally Puma. It does not install a separate web server.

Diagrams are saved by the editor as *.erd.png files under docs/erd/ in the Rails application. Use a different directory inside the application with --diagrams-dir, for example:

bundle exec canvas_erd --diagrams-dir db/diagrams

The editor opens the most recently modified saved diagram when it starts. Its saved-diagram menu loads other files directly. You can also open a specific diagram with bundle exec canvas_erd path/to/domain.erd.png.

• Drag tables to reposition them.
• Use the table sidebar to add or remove tables without losing their positions.
• Select one or more tables to color their headers and visually group related tables.
• Use Layout tables to rearrange the tables currently on the canvas with ELK without moving notes or hidden tables.
• Pinch over the canvas or use the toolbar buttons to zoom.
• Use a two-finger trackpad gesture to pan. Space-drag remains available as a keyboard fallback, and Fit diagram resets the view.
• Add editable notes with Add note. Notes support paragraph styles, emphasis, alignment, and text and background colors; new notes inherit the last touched note's style.
• Draw and style arrows with independent endpoint heads. Selecting an arrow immediately exposes its movable endpoints.
• Draw grouping frames behind the diagram, then edit their labels, colors, and border styles.
• Relationship cardinalities use crow's-foot notation at table edges, with exact text retained for uncommon numeric ranges.
• Use Refresh schema after a database migration to update columns and relationships. Existing table positions, selections, notes, and the current view are preserved; new tables start unselected.
• Edit the diagram name, then use Save (or ⌘S/Ctrl-S) to write the complete diagram into the Rails application as a normal *.erd.png image with its editable schema, layout, notes, selection, and viewport embedded inside it. Select a saved diagram from the menu to reopen it, or use New to start an “Untitled ERD.”

CanvasERD refreshes the model classes already loaded by the server. Restart CanvasERD after adding or renaming model classes or changing model code. Image optimization tools may remove the CanvasERD metadata required to edit a diagram again.

The editor binds only to 127.0.0.1 and does not expose the Rails application over the network.

After loading the Rails application, generate a JSON-safe schema hash with:

schema = CanvasERD::Diagram.create

The schema contains entities, attributes, relationships, and specializations with stable identifiers. Relationship cardinality ranges use nil as an unbounded maximum.

Run the tests:

bundle exec rake test

Build the gem:

bundle exec rake build

CanvasERD is available under the MIT License. Dependencies remain subject to their included licenses.

Fabric.js 7.4.0 is vendored under lib/canvas_erd/web/vendor. Its license is included in licenses/FABRIC-JS-LICENSE.txt. elkjs 0.12.0 is vendored there as a browser API and Web Worker. Its source is available from the elkjs project, and its license is included in licenses/ELKJS-LICENSE.md. Icons from iconoir directly embedded in the HTML, and it's license is included in licenses/ICONOIR-LICENSE.