---
id: paracelsus
version: "0.15.0"
license: MIT License Copyright (c) 2023, Robert Hafner Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record)
license_treatment: permissive
maintenance: aging
---

# paracelsus — Visualize SQLAlchemy Databases using Mermaid or Dot Diagrams.

License: permissive · Maintenance: aging · Downloads: 203.9K/mo

## 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 above — 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

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

- License: MIT License Copyright (c) 2023, Robert Hafner Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 203.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

sqlalchemy erd generator, database diagram from models, mermaid diagram from sqlalchemy, entity relationship diagram tool, visualize database schema, sqlalchemy to diagram, database documentation generator, documentation-generation, sqlalchemy, schema-visualization

[View on SkillFed](https://skillfed.io/packages/paracelsus) · [View on PyPI](https://pypi.org/project/paracelsus/)