Getting eralchemy working on MacOS in 2023

I wanted to generate a quick and dirty entity-relationship diagram for a database that's new to me and went looking for tools to help. There's a heap out there!

I stumbled upon eralchemy and figured I'd use this opportunity to try something different.

Getting it working on MacOS was a little bit of a struggle, so here's a quick TIL.

First, let's get the dependencies installed. This means installing Graphviz to generate the diagram and psycopg2 for PostgreSQL support (check the docs for other database engines).

Graphviz with Homebrew:

brew install graphviz

Psycopg2 as a binary with pip:

python3 -m pip install --user psycopg2-binary

Once they are installed we need to install eralchemy itself. This requires a couple of extra arguments to force it to use the Homebrew-installed version of Graphviz (Github Issue):

python3 -m pip install --user --global-option=build_ext --global-option="-I$(brew --prefix graphviz)/include/" --global-option="-L$(brew --prefix graphviz)/lib/" eralchemy

Running it now will result is an error. eralchemy isn't compatible with the latest version of [SQLAlchemy] and the version in the setup.py isn't pinned (Github Issue). Get around this by installing an older version:

python3 -m pip install 'sqlalchemy<1.4'

Finally, you're ready to generate a diagram!

The first command generates a plain text .er file in an erd compatible format:

eralchemy -i 'postgresql+psycopg2://username:password@localhost:5432/database' -o erd.er

Then you can use eralchemy again to output a PDF generate by Graphviz:

eralchemy -i erd.er -o erd.pdf

Enjoy the mess that is your project's database schema!