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.
Installation
Add CanvasERD to the development group in the Rails application's Gemfile:
group :development do
gem "canvas_erd", require: false
endThen run bundle install. CanvasERD requires Ruby 3.3 or newer, Active Record 7.0 or newer, and a Rack server available in the Rails bundle.
Usage
From a Rails application root, run:
bundle exec canvas_erdCanvasERD 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/diagramsThe 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.
Editor controls
- Drag tables to reposition them.
- Use the table sidebar to add or remove tables without losing their positions.
- Toggle scopes in the table sidebar to show a model's scope source in a code box linked to its table. Only scopes declared in the Rails application (including its concerns) are shown.
- 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.
- Add syntax-highlighted code boxes with Add code, choosing the language and a small, medium, or large font from the formatting toolbar. Add source file shows a read-only snippet of a file in the Rails application, with path autocompletion from the application's files (respecting
.gitignore) and optional start and end lines. Select the snippet to change its path or lines from the toolbar, or to toggle line numbers (which follow the source file). Click line numbers to highlight lines, and Shift-click to highlight or clear a range to match the last line clicked; Refresh schema re-reads it. Highlighting uses Rouge. - 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.pngimage 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.
Domain adapter
After loading the Rails application, generate a JSON-safe schema hash with:
schema = CanvasERD::Diagram.createThe schema contains entities, attributes, relationships, and specializations with stable identifiers. Relationship cardinality ranges use nil as an unbounded maximum.
Development
Run the tests:
bundle exec rake testBuild the gem:
bundle exec rake buildLicense
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.