ERAlchemy: Entity-Relation Diagram Generator

Common errors

• ValueError: Program dot not found in path.

  cause ERAlchemy relies on Graphviz (specifically the `dot` executable) to render diagrams, but the `dot` program is not found in your system's PATH.
  fix Install Graphviz on your system. For Debian/Ubuntu: `sudo apt install graphviz libgraphviz-dev`. For macOS: `brew install graphviz`. For Windows, download and install Graphviz from their official website and ensure its `bin` directory is added to your system's PATH environment variable.

• error: Microsoft Visual C++ 14.0 is required.

  cause During the installation of `eralchemy` on Windows, its dependency `pygraphviz` attempts to compile, which requires Microsoft Visual C++ build tools.
  fix Install the 'Build Tools for Visual Studio' from Microsoft's website and ensure that the C++ build tools are selected during installation. Alternatively, install `eralchemy` using Anaconda/Conda via `conda install -c conda-forge eralchemy` which often handles these dependencies better on Windows.

• Running eralchemy gives error on Win 10. Please install application. using "pip install application."

  cause This error can occur due to missing or improperly installed database drivers or underlying issues with `pygraphviz`'s Windows installation, sometimes masked by a generic 'install application' message.
  fix Ensure Graphviz is properly installed and its `bin` directory is in the system PATH. For specific database drivers (e.g., Oracle, MySQL), ensure they are also correctly installed (e.g., `pip install cx_Oracle` or `pip install mysqlclient`). If issues persist on Windows, consider using Windows Subsystem for Linux (WSL) or a Docker environment.

• eralchemy isn't compatible with the latest version of [SQLAlchemy]

  cause The `eralchemy` library (version 1.6.0) has known incompatibilities with SQLAlchemy versions 1.4 and newer, which can lead to various runtime errors.
  fix Downgrade your SQLAlchemy installation to a version prior to 1.4 by running `pip install 'sqlalchemy<1.4'`.

Warnings

• gotcha ERAlchemy fundamentally requires the Graphviz program to be installed on your system. It is not a Python package dependency handled by pip; you must install it separately according to your operating system's instructions (e.g., `apt-get install graphviz`, `brew install graphviz`). Without Graphviz, `render_er` will fail.
  Fix: Install Graphviz on your system and ensure its executables are available in your system's PATH. Refer to the official Graphviz documentation for detailed installation instructions.
• gotcha When installing `eralchemy[all]` to use `pygraphviz`, compilation issues can occur due to `pygraphviz`'s reliance on Graphviz's C libraries. This typically manifests as 'command 'gcc' failed' or similar errors during `pip install`.
  Fix: Ensure Graphviz and its development headers (e.g., `graphviz-dev` on Debian/Ubuntu, or Xcode Command Line Tools on macOS) are installed *before* attempting to install `pygraphviz` or `eralchemy[all]`. If issues persist, consider using the default rendering backend without `pygraphviz`.
• gotcha The project's development activity has slowed, with fewer updates and new features compared to its earlier history. While functional for its core purpose, this might mean slower adoption of newer SQLAlchemy features or resolutions for niche compatibility issues.
  Fix: Be mindful of this if working with very new SQLAlchemy versions or complex model structures that push the boundaries of common ER diagram representations. Test thoroughly if encountering unexpected rendering issues.
• gotcha ERAlchemy might have limitations in accurately representing highly complex SQLAlchemy models, such as polymorphic inheritance, custom relationship types, or many-to-many relationships without explicit association tables. The generated diagrams might simplify or omit certain details.
  Fix: Verify the generated diagram against your actual model to ensure correctness. For highly complex cases, manual adjustments to the diagram or using an `eralchemy` 'meta' file for declarative definitions might be necessary to achieve the desired representation.

Install

• pip install eralchemy Basic installation
• pip install eralchemy[all] With PyGraphviz support (optional)

Imports

• render_er

  from eralchemy import render_er

Quickstart

This quickstart demonstrates how to generate an ER diagram from SQLAlchemy models using `eralchemy`. It creates a simple SQLite database with two related tables (`User` and `Email`) and then uses `render_er` to generate a PNG file. Crucially, the external Graphviz program must be installed on your system for rendering to succeed.

from sqlalchemy import create_engine, Column, Integer, String, ForeignKey
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker, relationship
from eralchemy import render_er
import os

# 1. Define SQLAlchemy models
Base = declarative_base()

class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    name = Column(String(50), nullable=False)
    emails = relationship('Email', back_populates='user')

class Email(Base):
    __tablename__ = 'emails'
    id = Column(Integer, primary_key=True)
    address = Column(String(100), nullable=False, unique=True)
    user_id = Column(Integer, ForeignKey('users.id'))
    user = relationship('User', back_populates='emails')

# 2. Create a dummy database and tables
db_url = "sqlite:///./er_example.db"
engine = create_engine(db_url)
Base.metadata.create_all(engine)

# 3. Generate the ER diagram
output_file = "er_diagram.png"

# IMPORTANT: Graphviz must be installed on your system for this to work.
# Instructions for common OS:
#   - Debian/Ubuntu: sudo apt-get install graphviz
#   - macOS: brew install graphviz
#   - Windows: Download and install from graphviz.org, then add to PATH.

try:
    render_er(db_url, output_file)
    print(f"ER diagram generated to {output_file}")
    print(f"To view it, ensure Graphviz is installed and open {output_file}")
except Exception as e:
    print(f"Failed to generate ER diagram. Ensure Graphviz is correctly installed and in your system's PATH. Error: {e}")
finally:
    # Clean up the dummy database file if it was created
    if os.path.exists("./er_example.db"):
        pass # os.remove("./er_example.db") # Uncomment to remove DB file after run