paracelsus

What it is and what it does

Paracelsus is a command-line tool that reads your SQLAlchemy ORM models and automatically generates Entity Relationship Diagrams. It works by importing your model modules and inspecting the SQLAlchemy base class registry, then outputting diagrams in either Mermaid or Dot format. Mermaid diagrams render natively in many documentation systems and version control platforms, while Dot format can be further processed with GraphViz tools to create SVG or PNG images.

The tool is designed primarily for documentation and CI/CD workflows. You can generate diagrams on demand, inject them directly into markdown files with automatic updates, or use the `--check` flag to verify that documentation stays in sync with your schema. It supports filtering tables by inclusion or exclusion patterns, customizing column sort order, and handling SQLAlchemy type parameters that might break diagram rendering.

Use it for:

• Auto-generate database schema diagrams in project README files and keep them synchronized with model changes via CI/CD.
• Create visual documentation of complex database relationships for team onboarding and design review.
• Embed Mermaid diagrams directly in markdown documentation that renders in GitHub, GitLab, or similar platforms.
• Validate that database documentation is current by running `--check` in precommit hooks or CI pipelines.
• Export Dot format diagrams for further editing in GraphViz or conversion to PNG/SVG for presentations.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Paracelsus generates Entity Relationship Diagrams from SQLAlchemy models, outputting them as Mermaid or Dot format for visualization and documentation.

Yes, if you use SQLAlchemy and need to document or visualize your database schema. The tool is straightforward, has low dependencies, and solves a real documentation problem. The aging maintenance status is a minor concern but not a blocker—the core feature is stable and unlikely to break with new SQLAlchemy releases. Install it if you want automated, version-controlled schema diagrams; skip it if your schema is trivial or you prefer manual diagram tools.

Install

paracelsus on PyPI

pip install paracelsus

uv add paracelsus

poetry add paracelsus

Installing paracelsus

Before you install

Low install friction with a pure Python wheel and five straightforward dependencies. Maintenance status is aging—last release was 222 days ago—so expect slower response to issues, though the package appears stable for its core use case.

License in practice

MIT License permits free use, modification, and distribution with minimal restrictions, making it suitable for both open-source and commercial projects.

Quickstart

pip install paracelsus

paracelsus graph myapp.models.base:Base --import-module "myapp.models:*"

# or inject into markdown:
paracelsus inject README.md myapp.models.base:Base --import-module "myapp.models:*"

Requires Python 3.10 or later. SQLAlchemy models must be imported before diagram generation; the package reads the model registry, similar to Alembic's migration workflow.

Verify before relying

• Whether GraphViz (dot command) must be installed separately to generate SVG/PNG output, or if it is optional for Mermaid-only workflows.
• Performance characteristics when handling large schemas with many tables and relationships.

Package facts

Evidence: paracelsus-0.15.0-py3-none-any.whl

Tags

More Front-Ends packages