https://github.com/Alexis-benoist/eralchemy
Entity Relation Diagrams generation tool
https://github.com/Alexis-benoist/eralchemy
database documentation-tool mysql postgresql schema sql sqlalchemy visualization
Last synced: 4 months ago
JSON representation
Entity Relation Diagrams generation tool
- Host: GitHub
- URL: https://github.com/Alexis-benoist/eralchemy
- Owner: eralchemy
- License: apache-2.0
- Created: 2015-04-29T21:07:23.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2025-04-30T22:09:59.000Z (6 months ago)
- Last Synced: 2025-06-27T00:14:28.027Z (4 months ago)
- Topics: database, documentation-tool, mysql, postgresql, schema, sql, sqlalchemy, visualization
- Language: Python
- Homepage:
- Size: 1.63 MB
- Stars: 1,243
- Watchers: 25
- Forks: 122
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- Changelog: NEWS.rst
- License: LICENSE
Awesome Lists containing this project
- awesome-postgresql - ERAlchemy - A tool to generate Entity-Relationship (ER) diagrams from PostgreSQL databases. (Data Modeling and Schema Design)
README
[](LICENSE)
[](https://pypi.org/project/ERAlchemy/)
[](https://pypi.org/project/eralchemy/)
[](https://github.com/eralchemy/eralchemy/actions/workflows/unit.yaml)
[](https://app.codecov.io/gh/eralchemy/eralchemy/tree/main)
# Entity relation diagrams generator
eralchemy generates Entity Relation (ER) diagram (like the one below) from databases or from SQLAlchemy models.
## Example
## Quick Start
### Install
To install eralchemy, just do:
$ pip install eralchemy
### Graph library flavors
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.
The `graphviz` library is the default if both are installed.
`eralchemy` requires [GraphViz](http://www.graphviz.org/download) 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.
### Install using conda
There is also a packaged version in conda-forge, which directly installs the dependencies:
$ conda install -c conda-forge eralchemy
### Usage from Command Line
#### From a database
$ eralchemy -i sqlite:///relative/path/to/db.db -o erd_from_sqlite.pdf
The database is specified as a [SQLAlchemy](https://docs.sqlalchemy.org/en/20/core/engines.html#database-urls)
database url.
#### From a markdown file.
$ 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
#### From a Postgresql DB to a markdown file excluding tables named `temp` and `audit`
$ eralchemy -i 'postgresql+psycopg2://username:password@hostname:5432/databasename' -o filtered.er --exclude-tables temp audit
#### From a Postgresql DB to a markdown file excluding columns named `created_at` and `updated_at` from all tables
$ eralchemy -i 'postgresql+psycopg2://username:password@hostname:5432/databasename' -o filtered.er --exclude-columns created_at updated_at
#### From a Postgresql DB to a markdown file for the schemas `schema1` and `schema2`
$ eralchemy -i 'postgresql+psycopg2://username:password@hostname:5432/databasename' -s "schema1, schema2"
#### Specify Output Mode
$ eralchemy -i 'markdown_file.er' -o erd_from_markdown_file.md -m mermaid_er
### Usage from Python
```python
from eralchemy import render_er
## Draw from SQLAlchemy base
render_er(Base, 'erd_from_sqlalchemy.png')
## Draw from database
render_er("sqlite:///relative/path/to/db.db", 'erd_from_sqlite.png')
```
## Architecture
```mermaid
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.
## Contribute
Every feedback is welcome on the [GitHub issues](https://github.com/eralchemy/eralchemy/issues).
### Development
Install the development dependencies using
$ pip install -e .[ci,dev]
Make sure to run the pre-commit to fix formatting
$ pre-commit run --all
All tested PR are welcome.
## Running tests
This project uses the pytest test suite.
To run the tests, use : `$ pytest` or `$ tox`.
Some tests require having a local PostgreSQL database with a schema named test in a database
named test all owned by a user named eralchemy with a password of eralchemy.
If docker compose is available, one can use `docker compose up -d` for this purpose.
You can deselect the tests which require a PostgreSQL database using:
$ pytest -m "not external_db"
## Publishing a release
$ rm -r dist && python -m build && python3 -m twine upload --repository pypi dist/*
## Notes
ERAlchemy was inspired by [erd](https://github.com/BurntSushi/erd), though it is able to render the ER diagram directly
from the database and not just only from the `ER` markup language.
Released under an Apache License 2.0