erdalchemy 0.2.0

Interactive ERD visualization for SQLAlchemy 2.0 models

erdalchemy

Interactive ERD visualizer for SQLAlchemy 2.0 models. Introspects your DeclarativeBase metadata and generates diagram files with no manual configuration required.

• Drag-and-drop interactive HTML output
• Auto-layout via force-directed algorithm
• Hover highlighting for tables and relationships
• Export to HTML, SVG, PNG, and PDF
• Built-in color themes and per-table color overrides
• Multi-schema support with visual grouping and cross-schema FKs
• Zero dependencies beyond SQLAlchemy

Installation

pip install erdalchemy

PNG and PDF export require an optional dependency:

pip install "erdalchemy[all]"

Quick start

from sqlalchemy_erd import generate_erd
from myapp.models import Base

generate_erd(Base, output="erd.html")

CLI

# Interactive HTML (default)
sqlalchemy-erd myapp.models:Base

# Specific format and output path
sqlalchemy-erd myapp.models:Base --format svg --output erd.svg

# With theme and custom title
sqlalchemy-erd myapp.models:Base --format png --theme blue --title "My Schema"

# Per-table color overrides as JSON
sqlalchemy-erd myapp.models:Base --colors '{"users": "#1d4ed8", "orders": "#059669"}'

# High-resolution PNG
sqlalchemy-erd myapp.models:Base --format png --scale 3

# Only include specific database schemas
sqlalchemy-erd myapp.models:Base --schemas public,billing,audit

# Tune layout parameters
sqlalchemy-erd myapp.models:Base --k-repulse 50000 --k-attract 0.05 --ideal-len 350

Python API

from sqlalchemy_erd import generate_erd
from myapp.models import Base

generate_erd(Base, output="erd.html", format="html")
generate_erd(Base, output="erd.svg",  format="svg")
generate_erd(Base, output="erd.png",  format="png", scale=2)   # requires cairosvg
generate_erd(Base, output="erd.pdf",  format="pdf")             # requires cairosvg

# Only include specific database schemas
generate_erd(Base, output="erd.html", schemas=["public", "billing", "audit"])

# Tune layout parameters
generate_erd(Base, output="erd.html", k_repulse=50000, k_attract=0.05, ideal_len=350)

Themes

Five built-in themes: default, blue, green, dark, rose.

Preview images for each theme are available in examples/themes/.

generate_erd(Base, theme="dark")

Per-table color overrides let you assign any hex color to individual tables while keeping the rest of the theme intact:

generate_erd(
    Base,
    theme="default",
    table_colors={
        "users":    "#1e40af",
        "orders":   "#065f46",
        "products": "#9f1239",
    },
)

Layout tuning

The force-directed layout can be customized via four parameters:

Parameter	Default	Description
k_repulse	35000	Repulsion strength between all nodes. Increase to spread tables further apart.
k_attract	0.1	Attraction strength between connected nodes. Higher values pull FK-related tables closer.
k_align	0.02	Horizontal-alignment force. Pushes connected tables to the same Y, favoring side-by-side placement.
ideal_len	280	Target edge length (px) between connected tables.

Supported column types

SQLAlchemy type	Badge
Primary key	PK
Foreign key	FK
String	string
Text	text
Integer / BigInteger / SmallInteger	int / bigint / smallint
Float / Numeric	float / numeric
Date	date
DateTime	datetime
Boolean	bool
JSON	json
Uuid	uuid

Nullable columns display a ? suffix (e.g. text?, date?).

Relationship types

Cardinality	Line style
1:N	Solid with arrow
N:N	Dashed with arrow
Cross-schema FK	Dashed with longer gaps

Examples

See the examples/ directory:

• examples/blog/ - blog schema (User, Post, Comment)
• examples/ecommerce/ - 1:N chains (Category, Product, Order, Customer, OrderItem)
• examples/university/ - N:N via association tables (Student, Course, Professor, Department)
• examples/hr/ - 1:1 and 1:N (Employee, EmployeeProfile, Department, Project)
• examples/multi_schema/ - multi-schema with cross-schema FKs (public, billing, audit)

License

MIT