erdify 0.6.0rc2

Generate PlantUML ERD diagrams from SQLModel, SQLAlchemy, Django, Pydantic and dataclass models

🗃️ erdify

🚀 Generate beautiful PlantUML Entity Relationship Diagrams from your SQLModel, SQLAlchemy, Django, Pydantic and dataclass models automatically!

erdify parses your model files using AST (Abstract Syntax Tree) and generates comprehensive ERD diagrams in PlantUML format. It supports SQLModel, SQLAlchemy 2.0, Django ORM, Pydantic and standard-library dataclasses. No database connection required!

✨ Features

• 📊 Automatic ERD Generation - Parse your models and generate PlantUML diagrams
• 🧬 5 Frameworks - SQLModel, SQLAlchemy 2.0, Django ORM, Pydantic and dataclasses
• 🔍 AST-Based Parsing - No imports needed, works with any valid Python code
• 🎯 Zero Runtime Dependencies - Uses only Python standard library
• 🔗 Relationship Detection - Automatically detects foreign keys and relationships
• 🔑 Key Inference - --infer-keys derives PK/FK from field names for keyless models
• 🚫 Exclude Patterns - Filter out entities by class or table name with glob patterns
• 🎚️ Source Filtering - Restrict the diagram to specific model kinds with --sources
• ⚙️ Config File - Commit options under [tool.erdify] in pyproject.toml
• ✅ Drift Check - --check fails CI/pre-commit when the committed diagram is stale
• 📦 Inheritance Support - Resolves fields from base classes and mixins
• 🏷️ Enum Support - Includes enum definitions in the diagram
• 🔄 Link Table Detection - Identifies many-to-many association tables structurally
• 🧜 PlantUML & Mermaid - --format outputs PlantUML and/or Mermaid (renders natively on GitHub)
• 🎨 Beautiful Output - Clean, readable diagrams with proper styling

🚀 Quick Start

# Run without installing (or `pip install erdify`)
uvx erdify ./src/database -o erd.puml

# Output to stdout, with a custom title
erdify ./src/models --title "My Database Schema"

See the documentation for installation options, the full CLI, the Python API and more.

🧬 One Schema, Five Frameworks

The snippets below all describe the same User / Order schema — only the syntax differs. Each one produces the identical diagram:

ℹ️ The SQLModel, SQLAlchemy and Django versions declare keys explicitly (Django via its implicit id and ForeignKey). Pydantic and dataclasses have no key concept, so they are rendered with --infer-keys (id → PK, <x>_id → FK) to match. The runnable sources live in docs/examples/.

SQLModel	SQLAlchemy 2.0
from sqlmodel import ( Field, Relationship, SQLModel, ) class User(SQLModel, table=True): __tablename__: str = "user" id: int = Field(primary_key=True) name: str email: str orders: list["Order"] = Relationship( back_populates="user") class Order(SQLModel, table=True): __tablename__: str = "order" id: int = Field(primary_key=True) user_id: int = Field( foreign_key="user.id") total: float user: "User" = Relationship( back_populates="orders")	from sqlalchemy import ForeignKey from sqlalchemy.orm import ( DeclarativeBase, Mapped, mapped_column, relationship, ) class Base(DeclarativeBase): ... class User(Base): __tablename__ = "user" id: Mapped[int] = mapped_column( primary_key=True) name: Mapped[str] = mapped_column() email: Mapped[str] = mapped_column() orders: Mapped[list["Order"]] = ( relationship(back_populates="user")) class Order(Base): __tablename__ = "order" id: Mapped[int] = mapped_column( primary_key=True) user_id: Mapped[int] = mapped_column( ForeignKey("user.id")) total: Mapped[float] = mapped_column() user: Mapped["User"] = relationship( back_populates="orders")
Pydantic --infer-keys	Dataclass --infer-keys
from pydantic import BaseModel class User(BaseModel): id: int name: str email: str orders: list["Order"] = [] class Order(BaseModel): id: int user_id: int total: float user: "User"	from dataclasses import dataclass, field @dataclass class User: id: int name: str email: str orders: list["Order"] = field( default_factory=list) @dataclass class Order: id: int user_id: int total: float user: "User" = None
Django ORM
from django.db import models class User(models.Model): # implicit `id` PK; CharField/EmailField -> str name = models.CharField(max_length=100) email = models.EmailField() class Meta: db_table = "user" class Order(models.Model): user = models.ForeignKey( # -> user_id : int foreign key column User, on_delete=models.CASCADE) total = models.FloatField() # -> float class Meta: db_table = "order"

How each framework is detected & parsed:

Framework	Detected by	Keys	Relationships
SQLModel	table=True	Field(primary_key=…, foreign_key=…)	Relationship()
SQLAlchemy 2.0	__tablename__ + Mapped[...] columns	mapped_column(primary_key=…), ForeignKey(...)	relationship() (lowercase)
Django ORM	models.Model subclass	primary_key=True or implicit id, ForeignKey/OneToOneField	ForeignKey (N:1), OneToOneField (1:1), ManyToManyField (M:N, incl. through=)
Pydantic	BaseModel subclass (incl. transitive)	--infer-keys only	nested model refs (user: User, list["Order"])
Dataclass	@dataclass decorator	--infer-keys only	nested model refs

ℹ️ Mixins / abstract bases (e.g. a SQLAlchemy mixin without __tablename__, or a Django class Meta: abstract = True base) are not drawn as tables, but their columns are inherited into concrete entities.

For a worked example with the generated PlantUML, see the Frameworks Overview; for Django specifics see Django ORM.

📚 Documentation

• Installation — pip, uv, pipx, or run with uvx
• CLI & Python API — all CLI options, running as a module, and the Python API
• Output Formats — PlantUML & Mermaid, --format, output naming
• Filtering & Key Inference — --exclude, --exclude-paths, --sources, --infer-keys
• Viewing the Diagram — render online, locally with PlantUML, or in VS Code
• CI/CD & pre-commit — automate ERD generation in CI and on commit
• Frameworks Overview — a worked example with the generated PlantUML output
• Django ORM — Django-specific parsing details

📋 Supported Features

Feature	Status	Notes
Primary Keys	✅	Field(primary_key=True)
Foreign Keys	✅	Field(foreign_key="table.column")
Nullable Fields	✅	str | None or Optional[str]
Default Values	✅	Field(default=value)
Indexes	✅	Field(index=True)
Enums	✅	Python Enum classes
Relationships	✅	Relationship()
Inheritance	✅	Mixin classes supported
Link Tables	✅	Many-to-many detection
Custom Table Names	✅	__tablename__ attribute
Exclude Patterns	✅	--exclude glob on class/table name
Key Inference	✅	--infer-keys for Pydantic/dataclass (id, <x>_id)
SQLModel	✅	Field() / Relationship()
SQLAlchemy 2.0	✅	Mapped[...] / mapped_column()
Pydantic	✅	BaseModel subclasses, nested refs as relationships
Dataclass	✅	@dataclass, nested refs as relationships

🗺️ Roadmap

Recently shipped:

Feature	Status	Description
Exclude Option	✅ Done	Exclude tables or entities from ERD generation using glob patterns
SQLAlchemy Support	✅ Done	Native support for SQLAlchemy 2.0 (Mapped / mapped_column) models
Pydantic Support	✅ Done	Generate ERDs from Pydantic models, with optional --infer-keys
Dataclass Support	✅ Done	Support for standard Python dataclasses with type annotations

Have a feature request? Please open an issue on GitHub to discuss it!

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

🔒 Security

For security concerns, please see SECURITY.md.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

erdify stands on the shoulders of great open-source projects:

Supported model frameworks

• SQLModel - The awesome SQL database library
• SQLAlchemy - The Python SQL toolkit and ORM
• Django - The web framework whose ORM models erdify parses
• Pydantic - Data validation using Python type hints
• dataclasses - Python standard-library data classes

Rendering & output

• PlantUML - For the diagram rendering
• Graphviz - Layout engine behind PlantUML's ER diagrams

Tooling & infrastructure

• uv - Packaging, builds and dependency management
• Ruff - Linting and formatting
• mypy - Static type checking
• pytest - Testing framework
• pre-commit - Git hook management

Community

• Contributor Covenant - Our Code of Conduct
• Keep a Changelog - Changelog format
• And everyone who contributes issues, ideas and pull requests 💜

---

Made with ❤️ by Devsuit GmbH