SQLAlchemy ER Diagram Generator

English | 日本語 | 简体中文

A minimalist project to visualize SQLAlchemy data models as ER diagrams without creating a database or using third-party services.

Introduction

This project offers a lightweight solution allowing developers to generate ER diagrams directly from SQLAlchemy model code, avoiding duplication of effort between design and development phases. Once designed, the model code can be used directly in production.

Optimized specifically for Windows environments, eliminating the need to compile complex graphics library dependencies.

Key Features

• Zero Database Dependency - Generate ERDs directly from SQLAlchemy model metadata.
• Code as Design - The code written during the design phase is the final delivery code.
• Automatic Relationship Recognition - Foreign keys and associations are automatically converted into graph connections.
• Pure Python Implementation - Requires only Graphviz software installation; no complex C++ build environment needed.
• High-Definition Aesthetics - Generates 300 DPI high-def images in a modern minimalist style with automatic layout.

Quick Start

Prerequisites

1. Install uv (Recommended Python package manager):

   pip install uv
   
   # Or check the uv official site for other installation methods
   # https://docs.astral.sh/uv/getting-started/installation/#shell-autocompletion

2. Install Graphviz Software:

   • Download and install Graphviz for Windows
   • Important: Must check Add Graphviz to the system PATH for all users during installation.

Installation Steps

1. Initialize Environment and Dependencies:

   # Create virtual environment
   uv venv --python 3.13
   
   # Activate virtual environment
   .venv\Scripts\activate
   
   # Install dependencies
   uv pip install -r requirements.txt

Project Structure

my_project/
├── models.py          # SQLAlchemy model definitions (Design your table structure here)
├── generate_erd.py    # ER diagram generation script
└── requirements.txt   # Project dependencies

Usage Steps

1. Define Models - Write SQLAlchemy model classes in models.py.
2. Generate ER Diagram - Run the generation script:

   # Windows Powershell
   .venv\Scripts\python generate_erd.py

3. View Results - Check the generated image with timestamp in the output_ER/ directory.
4. Iterate - Adjust model code -> Re-run script -> View new diagram.

FAQ

Q: Script fails with FileNotFoundError: [WinError 2] ... A: This is because the system cannot find the Graphviz executable. Please ensure you have installed Graphviz software and added it to your system's PATH environment variable. You may need to restart your terminal after installation.

Dependencies

Package Name	Purpose	Description
sqlalchemy	ORM Framework	Defines data models
sqlalchemy-schemadisplay	Visualization Tool	Generates graph structure from models
pydot	Graphics Rendering	Generates PNG images