vdb — Interactive ERD visualiser for Rails

Mount a self-contained, D3-powered entity-relationship diagram in any Rails app. Zero asset-pipeline dependencies. Reads db/schema.rb, infers foreign keys, renders a live force-directed graph.

Get Started See Example GitHub

vdb ERD visualiser showing a blog schema with 7 tables and their relationships

The blog example app — 7 tables, crow's-foot cardinality, dark D3 canvas. Visit /dev/erd in any Rails app.

Features

📊

Auto-parsed schema

Reads db/schema.rb at request time. No generators, no separate config. Multiple schema files supported via tabs.

🔗

FK inference

Detects relationships from add_foreign_key declarations and implicit *_id column naming. Never misses a link.

✖

Crow's-foot notation

Every relationship line carries correct cardinality markers — crow's-foot for many, single-tick for one. 1:1 detected via unique indexes.

🔍

Table search

Type in the search box to instantly dim non-matching tables. Indispensable for schemas with 50+ tables.

👀

Relationship highlighting

Click any table header to highlight its direct neighbours and relationships; everything else fades back.

📍

Persistent positions

Drag nodes to rearrange, zoom in/out, fit to screen. Positions saved to localStorage per database so your layout survives refreshes.

🔒

Optional Basic Auth

Set username and password in the initializer to gate access. Secure comparison — no timing attacks.

⚡

Zero asset-pipeline deps

D3 v7 and Stimulus 3 loaded from CDN. Drop in the gem — no Webpacker, no importmaps, no asset recompilation needed.

Quick Start

Add the gem Add to your Gemfile inside the :development group:

group :development do
  gem 'vdb'
end

Mount the engine In config/routes.rb:

Rails.application.routes.draw do
  mount Vdb::Engine, at: '/dev/erd'
  # … rest of your routes
end

Visit the ERD Start your server and open http://localhost:3000/dev/erd. That's it — no configuration required.

Tip Run rails vdb:install to auto-mount the engine and generate a starter initializer in one step.

What you get

A self-contained dark-mode dashboard at /dev/erd that:

Renders all your tables as draggable node cards with columns and types
Draws relationship lines with correct crow's-foot / single-tick notation
Highlights foreign-key columns in cyan
Lets you search, zoom, fit-to-screen, and reset layout
Supports multiple schema files (e.g. a secondary audit_schema.rb) as tabs

Auto-excluded tables

Rails internals and Solid* framework tables are hidden automatically so your ERD stays clean:

active_storage_*, action_text_rich_texts
ar_internal_metadata, schema_migrations
solid_cache_*, solid_queue_*, solid_cable_*

Requirements

Dependency	Version
Ruby	≥ 3.1
Rails	≥ 7.0, < 9
D3.js	v7 (CDN)
Stimulus	v3 (CDN)