Repository files navigation

eralchemy generates Entity Relation (ER) diagram (like the one below) from databases or from SQLAlchemy models.

To install eralchemy, just do:

$ pip install eralchemy

To create Pictures and PDFs, eralchemy relies on either graphviz or pygraphviz.

You can use either

$ pip install eralchemy[graphviz]

or

$ pip install eralchemy[pygraphviz]

to retrieve the correct dependencies.Thegraphviz library is the default if both are installed.

eralchemy requiresGraphViz to generate the graphs and Python. Both are available for Windows, Mac and Linux.

For Debian based systems, run:

$ apt install graphviz libgraphviz-dev

before installing eralchemy.

There is also a packaged version in conda-forge, which directly installs the dependencies:

$ conda install -c conda-forge eralchemy

$ eralchemy -i sqlite:///relative/path/to/db.db -o erd_from_sqlite.pdf

The database is specified as aSQLAlchemydatabase url.

$ curl 'https://raw.githubusercontent.com/eralchemy/eralchemy/main/example/forum.er' > markdown_file.er$ eralchemy -i 'markdown_file.er' -o erd_from_markdown_file.pdf

$ eralchemy -i 'postgresql+psycopg2://username:password@hostname:5432/databasename' -o filtered.er --exclude-tables temp audit

$ eralchemy -i 'postgresql+psycopg2://username:password@hostname:5432/databasename' -o filtered.er --exclude-columns created_at updated_at

$ eralchemy -i 'postgresql+psycopg2://username:password@hostname:5432/databasename' -s "schema1, schema2"

$ eralchemy -i 'markdown_file.er' -o erd_from_markdown_file.md -m mermaid_er

fromeralchemyimportrender_er## Draw from SQLAlchemy baserender_er(Base,'erd_from_sqlalchemy.png')## Draw from databaserender_er("sqlite:///relative/path/to/db.db",'erd_from_sqlite.png')

When rendering dot files, it can be needed to adjust how some parts are visualized.This can be used to getcrowfoot relations, stars instead of underlines for primary keys or a top-bottom rendering instead the default left-right rendering.

It can be adjusted by manipulating the globalfrom eralchemy.cst import config dictionary.

Some helper functions exist likedot_star_primary,dot_top_down,dot_digraph anddot_crowfoot.The config can be reset usingreset_config.

This can be used like

fromeralchemyimportrender_erfromeralchemy.cstimportdot_crowfoot,dot_digraphdot_crowfoot()dot_digraph()render_er(Base,"forum.svg")

graph LR    subgraph Inputs        A[Markdown representation]        B[SQLAlchemy Schema]        C[Existing database]        D[Other ORM ?]    end    E[Intermediary representation]    subgraph Outputs        F[Markdown representation]        G[Graphviz code]        H[Drawing]    end    A --> E    B --> E    C --> E    D --> E    E --> F    E --> G    E --> H

Thanks to it's modular architecture, it can be connected to other ORMs/ODMs/OGMs/O*Ms.

Every feedback is welcome on theGitHub issues.

Install the development dependencies using

$ pip install -e .[dev,test]

Make sure to run the pre-commit to fix formatting

$ pre-commit run --all

All tested PR are welcome.

This project uses the pytest test suite.To run the tests, use :$ pytest or$ nox.

Some tests require having a local PostgreSQL database with a schema named test in a databasenamed test all owned by a user named eralchemy with a password of eralchemy.If docker compose is available, one can usedocker compose up -d for this purpose.You can deselect the tests which require a PostgreSQL database using:

$ pytest -m "not external_db"

$ rm -r dist && python -m build && python3 -m twine upload --repository pypi dist/*

ERAlchemy was inspired byerd, though it is able to render the ER diagram directlyfrom the database and not just only from theER markup language.

Released under an Apache License 2.0