Paracelsus

0.15.0 verified Mon Apr 27 auth: no python

Visualize SQLAlchemy databases using Mermaid or Graphviz (Dot) diagrams. Supports generating entity-relationship diagrams (ERDs) from SQLAlchemy models. Version 0.15.0, active development.

pip install paracelsus

Common errors

error AttributeError: module 'paracelsus' has no attribute 'generate_er_diagram' ↓

cause Importing the wrong submodule or using an outdated version.

fix

Ensure you have installed paracelsus>=0.12.0 and use: from paracelsus import generate_er_diagram

error TypeError: generate_er_diagram() missing 1 required positional argument: 'metadata' ↓

cause The function requires metadata as the first argument; in v0.15.0 it is not optional.

fix

Pass the metadata object: generate_er_diagram(metadata, ...)

error sqlalchemy.exc.InvalidRequestError: Could not reflect: database has no tables ↓

cause The database engine connected to an empty database or no tables exist.

fix

Ensure the database has tables or use a declarative base: generate_er_diagram(Base.metadata, ...)

error graphviz.backend.ExecutableNotFound: failed to execute ['dot', ...] ↓

cause Graphviz is not installed on the system; required for 'dot' format output.

fix

Install Graphviz system package (e.g., 'apt install graphviz' on Ubuntu or 'brew install graphviz' on macOS) or use format='mermaid'.

Warnings

gotcha The default output format changed in v0.12.0 from 'dot' to 'mermaid'. Ensure you specify format='mermaid' or format='dot' explicitly to avoid unexpected output. ↓

fix Always specify the format parameter: generate_er_diagram(metadata, format='mermaid') or generate_er_diagram(metadata, format='dot').

breaking In v0.15.0, the function signature changed; the 'metadata' parameter is now required as the first positional argument. Passing it as a keyword argument still works but ensure order. ↓

fix Call generate_er_diagram(metadata, ...) instead of relying on previous positional order.

gotcha Reflecting a database requires an active engine connection. If using a declarative base, use Base.metadata instead of reflecting. ↓

fix Use Base.metadata directly: generate_er_diagram(Base.metadata, ...).

Imports

generate_er_diagram
```
from paracelsus import generate_er_diagram
```
Primary function to generate diagram from SQLAlchemy metadata or declarative base.

Quickstart

Reflect database schema and generate a Mermaid ER diagram string.

from sqlalchemy import create_engine, MetaData
from paracelsus import generate_er_diagram

engine = create_engine('sqlite:///:memory:')
metadata = MetaData()
metadata.reflect(bind=engine)
diagram = generate_er_diagram(metadata, format='mermaid')
print(diagram)