{"id":10255,"library":"sqlalchemy-schemadisplay","title":"SQLAlchemy SchemaDisplay","description":"SQLAlchemy SchemaDisplay is a Python library (version 2.0) for generating visual diagrams from SQLAlchemy ORM models or directly from a database schema. It leverages the Graphviz engine to produce high-quality visualizations of database structures, showing tables, columns, relationships, and data types. Releases are primarily driven by feature additions and compatibility updates with SQLAlchemy.","status":"active","version":"2.0","language":"en","source_language":"en","source_url":"https://github.com/fschulze/sqlalchemy_schemadisplay","tags":["SQLAlchemy","diagramming","database","ORM","Graphviz"],"install":[{"cmd":"pip install sqlalchemy-schemadisplay graphviz","lang":"bash","label":"Basic Installation"},{"cmd":"sudo apt-get install graphviz # On Debian/Ubuntu\nbrew install graphviz # On macOS","lang":"bash","label":"Install Graphviz executable (required)"}],"dependencies":[{"reason":"Core ORM and schema reflection functionality.","package":"SQLAlchemy","optional":false},{"reason":"Python binding for the Graphviz diagramming software.","package":"graphviz","optional":false}],"imports":[{"symbol":"create_schema_graph","correct":"from sqlalchemy_schemadisplay import create_schema_graph"}],"quickstart":{"code":"import os\nfrom sqlalchemy import create_engine, Column, Integer, String\nfrom sqlalchemy.orm import declarative_base\nfrom sqlalchemy_schemadisplay import create_schema_graph\n\n# 1. Define your 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    email = Column(String(100), unique=True)\n\nclass Product(Base):\n    __tablename__ = 'products'\n    id = Column(Integer, primary_key=True)\n    name = Column(String(50), nullable=False)\n    price = Column(Integer)\n\n# 2. Create the graph and save it to a file\ntry:\n    # Using Base.metadata directly\n    graph = create_schema_graph(\n        metadata=Base.metadata,\n        show_datatypes=True,\n        show_labels=True,\n        rankdir='LR', # Left-to-right layout\n        orientation='portrait'\n    )\n    output_file = 'schema.png'\n    graph.write_png(output_file)\n    print(f\"Schema diagram saved to {output_file}\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Make sure Graphviz is installed on your system PATH and 'graphviz' Python package is installed.\")\n\n# Optional: Clean up (if you created a temporary database for reflection)\n# os.remove('test.db') if os.path.exists('test.db') else None","lang":"python","description":"This quickstart demonstrates how to define simple SQLAlchemy models using `declarative_base` and then use `create_schema_graph` to generate a PNG diagram representing their structure. It outputs a file named `schema.png` in the current directory. Remember that the Graphviz executable must be installed on your system for this to work."},"warnings":[{"fix":"Install Graphviz on your operating system (e.g., `sudo apt-get install graphviz` on Debian/Ubuntu, `brew install graphviz` on macOS, or from graphviz.org for Windows).","message":"The `create_schema_graph` function requires the external Graphviz executable (`dot` command) to be installed on your system and available in your PATH. Without it, the diagram generation will fail with a `FileNotFoundError`.","severity":"breaking","affected_versions":"All versions"},{"fix":"Ensure both `sqlalchemy-schemadisplay` and `graphviz` are installed: `pip install sqlalchemy-schemadisplay graphviz`.","message":"Forgetting to install the Python `graphviz` package alongside `sqlalchemy-schemadisplay` will result in a `ModuleNotFoundError` when `create_schema_graph` attempts to import it.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use `metadata=Base.metadata` for declarative models or `metadata=db_engine.metadata` for reflected schemas.","message":"When using `declarative_base`, you must pass `Base.metadata` to `create_schema_graph`, not the `Base` object itself. Passing `Base` directly will likely result in an `AttributeError`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Call a `write_` method on the returned graph object with a valid file path, e.g., `graph.write_png('my_schema.png')`.","message":"Outputting the diagram requires specifying the `filename` for methods like `write_png`, `write_svg`, etc. Also, ensure the directory has write permissions. If no filename is given, the graph object is returned but not saved.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Install the Graphviz software package for your operating system. For example, `sudo apt-get install graphviz` on Debian/Ubuntu, or `brew install graphviz` on macOS. Verify installation by running `dot -V` in your terminal.","cause":"The Graphviz command-line executable (`dot`) is not installed on your system or is not accessible in your system's PATH.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'dot'"},{"fix":"Install the Python `graphviz` package using pip: `pip install graphviz`.","cause":"The Python `graphviz` package, which is a dependency of `sqlalchemy-schemadisplay`, has not been installed.","error":"ModuleNotFoundError: No module named 'graphviz'"},{"fix":"Ensure you are passing `Base.metadata` (for declarative models) or an existing `MetaData` object to the `metadata` argument of `create_schema_graph`.","cause":"You are passing an instance of `Base` or the `Base` class itself to `create_schema_graph` instead of its `metadata` attribute.","error":"AttributeError: 'DeclarativeBase' object has no attribute 'metadata'"}]}