🗃️ 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 — and raw SQL DDL files (.sql) via the optional erdify[sql] extra. No database connection required!

✨ Features

• 🧬 5 Python Frameworks + SQL DDL - SQLModel, SQLAlchemy 2.0, Django ORM, Pydantic, dataclasses, and raw .sql files (via erdify[sql])
• 🔍 AST-Based Parsing - No imports needed, works with any valid Python code
• 🎯 Zero dependencies by default — core uses only the stdlib; SQL support is an opt-in extra (erdify[sql])
• 🔗 Relationship Detection - Foreign keys, relationships and many-to-many link tables
• 🧜 4 Output Formats - --format emits PlantUML, Mermaid (renders natively on GitHub), JSON, or a self-contained HTML preview
• 📝 Markdown Embed - --inject writes the diagram into a Markdown file between markers
• ⚙️ Config File - Store options under [tool.erdify] in pyproject.toml
• ✅ Drift Check - --check fails CI/pre-commit when the committed diagram is stale

See the full feature matrix for everything erdify recognizes.

🤔 Why erdify and not X?

erdify reads your source with the stdlib ast module, so it runs in a docs pipeline, a pre-commit hook or a CI job against a repository it cannot even install — and one command covers five frameworks plus raw SQL, where every other tool here covers one. That is a trade-off, not a free win: anything your code builds at runtime is invisible to it, and none of these tools renders images for you.

👉 Full comparison, including when to use something else

🚀 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:

erdify docs/examples/sqlmodel --inject README.md keeps the diagram below in this file. It is Mermaid, so GitHub renders it directly — and a pre-commit hook runs the same command with --check, so it cannot go stale:

erDiagram
    User {
        int id PK
        str name
        str email
    }
    Order {
        int id PK
        int user_id FK
        float total
    }
    Order }o--|| User : "user_id"

👉 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, --inject into Markdown, output naming
• Filtering & Key Inference — --exclude, --exclude-paths, --include, --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
• SQL DDL — generate ERDs from .sql files with erdify[sql]
• Comparison — erdify next to the other ERD generators
• Troubleshooting — symptom-first fixes for the common surprises
• Stability & Versioning — what a major, minor or patch release may change

📋 Supported Features

Primary/foreign keys, nullable fields, defaults, indexes, enums, relationships, inheritance, link tables, custom table names and per-framework specifics — see the full feature matrix in the docs.

💬 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