erdify 0.9.0

A zero-dependency ERD generator for your Python models — pure AST, no database required.

🗃️ 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
• 🧜 4 Output Formats - --format emits PlantUML, Mermaid (renders natively on GitHub), JSON, or a self-contained HTML preview
• 🎨 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 same User / Order schema in SQLModel, SQLAlchemy 2.0, Django, Pydantic and dataclasses — only the syntax differs. Each one produces the identical diagram:

👉 See the full side-by-side comparison and the detection/parsing table in the Frameworks Overview (with a worked example and Django specifics). The runnable sources live in docs/examples/.

📚 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

💬 Community

Questions, ideas, or want to show off an ERD erdify generated? Join the Discussions. For open-ended topics and feature direction, Discussions are the place; concrete bugs and proposals go to Issues.

🤝 Contributing

Contributions are welcome! Have a bug or a concrete feature request? Please open an issue, and see CONTRIBUTING.md for guidelines. Shipped changes are tracked in the changelog.

🔒 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
• Mermaid - Renders the --format mermaid / html output

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 💜

---

Created & maintained with ❤️ by devsuit GmbH