{"id":2020,"library":"eralchemy","title":"ERAlchemy: Entity-Relation Diagram Generator","description":"ERAlchemy is a Python library for generating Entity-Relation (ER) diagrams from SQLAlchemy models, declarative database metadata, or a simple text file format. It leverages the external Graphviz engine to visualize the relationships and can output diagrams in various formats such as PNG, SVG, and PDF. The current stable version is 1.6.0, with development activity having slowed in recent years, but it remains a functional tool for its primary purpose.","status":"maintenance","version":"1.6.0","language":"en","source_language":"en","source_url":"https://github.com/Alexis-benoist/eralchemy","tags":["ERD","diagrams","SQLAlchemy","Graphviz","database","visualization"],"install":[{"cmd":"pip install eralchemy","lang":"bash","label":"Basic installation"},{"cmd":"pip install eralchemy[all]","lang":"bash","label":"With PyGraphviz support (optional)"}],"dependencies":[{"reason":"An external system dependency required for rendering diagrams (e.g., PNG, SVG). Must be installed separately.","package":"Graphviz","optional":false},{"reason":"An optional Python binding to Graphviz, offering an alternative rendering backend. Installed via `eralchemy[all]`.","package":"pygraphviz","optional":true}],"imports":[{"symbol":"render_er","correct":"from eralchemy import render_er"}],"quickstart":{"code":"from sqlalchemy import create_engine, Column, Integer, String, ForeignKey\nfrom sqlalchemy.ext.declarative import declarative_base\nfrom sqlalchemy.orm import sessionmaker, relationship\nfrom eralchemy import render_er\nimport os\n\n# 1. Define SQLAlchemy models\nBase = declarative_base()\n\nclass User(Base):\n    __tablename__ = 'users'\n    id = Column(Integer, primary_key=True)\n    name = Column(String(50), nullable=False)\n    emails = relationship('Email', back_populates='user')\n\nclass Email(Base):\n    __tablename__ = 'emails'\n    id = Column(Integer, primary_key=True)\n    address = Column(String(100), nullable=False, unique=True)\n    user_id = Column(Integer, ForeignKey('users.id'))\n    user = relationship('User', back_populates='emails')\n\n# 2. Create a dummy database and tables\ndb_url = \"sqlite:///./er_example.db\"\nengine = create_engine(db_url)\nBase.metadata.create_all(engine)\n\n# 3. Generate the ER diagram\noutput_file = \"er_diagram.png\"\n\n# IMPORTANT: Graphviz must be installed on your system for this to work.\n# Instructions for common OS:\n#   - Debian/Ubuntu: sudo apt-get install graphviz\n#   - macOS: brew install graphviz\n#   - Windows: Download and install from graphviz.org, then add to PATH.\n\ntry:\n    render_er(db_url, output_file)\n    print(f\"ER diagram generated to {output_file}\")\n    print(f\"To view it, ensure Graphviz is installed and open {output_file}\")\nexcept Exception as e:\n    print(f\"Failed to generate ER diagram. Ensure Graphviz is correctly installed and in your system's PATH. Error: {e}\")\nfinally:\n    # Clean up the dummy database file if it was created\n    if os.path.exists(\"./er_example.db\"):\n        pass # os.remove(\"./er_example.db\") # Uncomment to remove DB file after run\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"1.x and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}