eralchemy: ER diagrams from databases and SQLAlchemy models

What eralchemy solves for database documentation

eralchemy addresses the gap between a database schema that already exists and an ER diagram that is easy to read. The README says it generates Entity Relation diagrams from databases or SQLAlchemy models. That makes it relevant to Python developers documenting relational designs, reviewing SQLAlchemy models, or producing a visual artifact from an existing schema. It can also read a Markdown-like `.er` representation, so a team can use a checked-in intermediate file rather than requiring direct database access for every diagram generation.

The supported inputs and outputs are broader than a single PDF export. The documented architecture places Markdown representation, SQLAlchemy schema, and existing database before an intermediary representation. From that representation, eralchemy can produce Markdown, Graphviz code, or a drawing. The repository describes the project as a diagram generator rather than a database administration tool. It does not claim to create tables, apply migrations, inspect application data, or synchronize a schema with an ER file. Those boundaries matter when selecting it for a documentation pipeline.

The project targets Python users and requires Python 3.10 or later. Its package metadata lists SQLAlchemy 1.4.18 or later as the core dependency. The optional rendering dependencies are `graphviz` and `pygraphviz`, while the README also requires GraphViz itself for generating graphs. This dependency split gives callers a choice between rendering implementations, but it also means installation is more involved than installing a pure Python package with a built-in renderer.

Inputs, intermediary representation, and Graphviz output

The central design is an intermediary representation. According to the README architecture, input is normalized into a common internal form, then sent to output paths for Markdown, Graphviz code, or a rendered drawing. This is a useful separation because the same schema source can be used for different deliverables. A developer can request a PDF for review, a PNG for a document, or a Mermaid representation for Markdown without maintaining separate diagrams.

Database input uses a SQLAlchemy database URL. The README gives SQLite and PostgreSQL examples, and the package depends on SQLAlchemy for database handling. SQLAlchemy model input goes through the Python API. The documented example passes a SQLAlchemy `Base` object to `render_er`. This means the model class must already expose the metadata and relationships that eralchemy can inspect. A model that is incomplete, dynamically constructed, or unavailable at render time will not produce the same result as a complete database schema.

Rendering is controlled through configuration functions in `eralchemy.cst`. The README names `dot_star_primary`, `dot_top_down`, `dot_digraph`, and `dot_crowfoot`, and also documents `reset_config`. These options change DOT output details such as primary-key markers, direction, directed graph style, and crowfoot relations. The configuration is global, as the README describes it as a dictionary named `config`. Global state is convenient for a short script but deserves attention in long-running services or test suites, because one rendering configuration can affect later calls until reset.

Installing eralchemy and producing a first diagram

The shortest documented installation installs the package from PyPI. This is sufficient for SQLAlchemy-based generation, but a complete rendering setup also needs GraphViz and one of the documented optional dependency groups.

Install the package with:

pip install eralchemy

The README says that GraphViz and Python are required for generating graphs. On Debian-based systems, its documented prerequisite command is:

apt install graphviz libgraphviz-dev

If the installation needs the Graphviz Python integration, choose one of the documented extras. The default rendering library is Graphviz if both backends are installed:

pip install eralchemy[graphviz]

Alternatively, use the PyGraphviz extra documented by the project:

pip install eralchemy[pygraphviz]

A first database-backed command can generate a PDF from a SQLite URL:

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

The command reads the database specified by the SQLAlchemy URL and writes the diagram to the named output path. The README also documents Python usage when the model object is already available:

from eralchemy import render_er

render_er(Base, 'erd_from_sqlalchemy.png')
render_er("sqlite:///relative/path/to/db.db", 'erd_from_sqlite.png')

The first call uses a SQLAlchemy base, while the second uses a database URL. The output extension changes the requested output artifact in the documented examples, including PDF, PNG, and SVG.

Filtering schemas and switching output modes

eralchemy includes command-line filters for tables and columns. The PostgreSQL example excludes tables named `temp` and `audit` while writing a Markdown-oriented output:

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

A related example removes common timestamp columns from every table:

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

These options are useful for reducing clutter, but they are selection filters rather than privacy controls. The README does not claim that excluded columns are removed from the source database, and no database changes are documented. It is also unclear from the README how filters interact with dependencies or relationship edges. Teams that need an exact view should check the generated file rather than assume that removing a table leaves every related edge in the intended state.

The `-s` option selects schemas. The documented command accepts a comma-separated value:

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

For Mermaid output, the `-m` option selects `mermaid_er`:

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

This flexibility helps fit a diagram into Markdown documentation, but each renderer and mode adds another compatibility surface. The README does not document rollback of a generated file, rendering error messages, or guarantees that every input mode supports every output mode. Those are practical checks before adding the command to CI.

Limitations of direct database and model rendering

The main limitation is that eralchemy can only render what the source exposes. A database-backed diagram depends on a valid SQLAlchemy URL, network or filesystem access, and permissions for the selected schema. The README demonstrates PostgreSQL with `postgresql+psycopg2`, but it does not document authentication handling beyond showing credentials in the URL. Keeping passwords in command history or CI logs is therefore an operational concern that the documentation leaves to the caller.

Model-backed rendering has a different constraint. The Python example assumes `Base` is defined and imported in scope, and eralchemy reads the schema represented by that object. It does not load application code or discover every possible mapping configuration automatically. If relationship metadata is incomplete, the output can be incomplete even though the database tables exist. If several SQLAlchemy versions are used in a project, the declared minimum is 1.4.18, but the README does not provide a compatibility matrix.

Another boundary is output ownership. eralchemy generates diagrams and representations; it does not present a browser-based editor for rearranging boxes, adding explanatory annotations, or merging diagrams. The README describes modular input and output paths, but it does not document a stable API for every internal representation type. Integrators should inspect the package API before depending on private modules. For a one-off export, the CLI is sufficient. For a custom documentation system, the documented `render_er` function and configuration helpers are safer starting points than undocumented internals, although the exact stability policy is not stated.

Maintenance, upgrades, and the Apache-2.0 boundary

The repository is not archived. Its last push was on 2026-05-05, and the listed `v1.7.0` release is dated 2026-05-05. Earlier listed releases are `v1.6.0` from 2025-09-18 and `v1.5.0` from 2024-09-17. The project therefore has recent release activity, while the README and repository metadata do not provide a detailed compatibility policy for every future SQLAlchemy or Graphviz release.

Upgrades should account for the two dependency layers. Python 3.10 or later and SQLAlchemy 1.4.18 or later are declared in `pyproject.toml`. Rendering also depends on GraphViz, with optional `graphviz` or `pygraphviz` integrations. A change in any of these packages can affect layout, output format, or installation behavior. The project provides development commands for pre-commit and pytest, including a way to deselect external database tests:

pytest -m "not external_db"

The full test setup can include a local PostgreSQL service started with the repository's Docker Compose configuration:

docker compose up -d

These are contributor and test workflows, not an end-user upgrade guarantee. The package is licensed under Apache-2.0. The license permits use and modification under its terms, including preservation of applicable notices and conditions. This is not legal advice. Organizations should review the license file and their distribution practices when embedding generated diagrams or redistributing modified software.

For comparison, a database GUI or schema designer generally offers manual editing and richer visual controls, while eralchemy is code- and CLI-oriented. Conversely, a diagram renderer that accepts only one native schema format can be simpler, but it would not match eralchemy's documented range of SQLAlchemy, database URL, and `.er` inputs. The practical distinction is automation and source-of-truth alignment, not the mere ability to draw rectangles and lines.

Editorial conclusion

Choose eralchemy when the source of truth is a SQLAlchemy model, a reachable database, or an `.er` file and the output must be generated as part of documentation. Do not choose it as a general-purpose visual editor or for database migrations, since it documents or renders schemas rather than changing them. Before adoption, verify Graphviz availability, the chosen rendering backend, and whether your database URL exposes the schemas and tables that the diagram must include. For a Python project, start with the documented `pip install eralchemy` path, confirm the output file is created, then test the optional filtering flags against representative schemas.

Frequently asked questions

Official sources

1. eralchemy/eralchemy on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases