Paracelsus

To generate a graph, you must provide the path to your SQLAlchemy Base class (using the module.path:Base syntax) and ensure all models are imported into the registry. Use the --import-module flag for each module containing models.

To perform a wildcard import (equivalent to from module import *), use the :* suffix. Note: Wrap the module name in quotes to prevent shell expansion.

# Specific module imports
paracelsus graph example_app.models.base:Base \
  --import-module "example_app.models.users" \
  --import-module "example_app.models.posts"

# Wildcard import
paracelsus graph example_app.models.base:Base --import-module "example_app.models:*"

Paracelsus can automatically update documentation by looking for specific HTML comment tags in your Markdown files. It replaces the content between these tags with a new Mermaid code block.

Markdown Setup:

## Schema
<!-- BEGIN_SQLALCHEMY_DOCS -->

<!-- END_SQLALCHEMY_DOCS -->

CLI Command: paracelsus inject <markdown_file> <base_class_path> [options]

CI/CD Integration: Use the --check flag. It returns exit code 0 if the file is up to date, and 1 if changes are required. This is ideal for precommit hooks or CI pipelines to ensure documentation stays in sync with the schema.

# Inject into a file
paracelsus inject db/README.md example_app.models.base:Base --import-module "example_app.models:*"

# Check for updates (for CI/CD)
paracelsus inject db/README.md example_app.models.base:Base --import-module "example_app.models:*" --check

The Paracelsus CLI is available via the paracelsus command once the package is installed. You can view the full list of available commands and options by using the --help flag.

paracelsus --help

Install the paracelsus package using pip. Ensure you install it in the same Python environment as your application code, as Paracelsus needs to import your SQLAlchemy models to generate diagrams.

pip install paracelsus

You can persist Paracelsus settings in your pyproject.toml file under the [tool.paracelsus] section. This avoids repeating flags in the CLI.

Supported keys:

• base: The SQLAlchemy base class path.
• imports: A list of modules to import.
• exclude_tables: List of tables to exclude.
• include_tables: List of tables to include.
• column_sort: Sorting strategy (key-based or preserve-order).
• omit_comments: Boolean to hide SQLAlchemy column comments.
• max_enum_members: Integer limit for enum members.
• type_parameter_delimiter: String delimiter for type parameters.

[tool.paracelsus]
base = "example.base:Base"
imports = [
  "example.models"
]
exclude_tables = [
  "comments"
]
column_sort = "preserve-order"
omit_comments = false
max_enum_members = 10
type_parameter_delimiter = "-"

Paracelsus can output diagrams in DOT format, which can be piped into the GraphViz dot tool to create images like SVG or PNG.

Generate SVG:

paracelsus graph <base_path> --import-module <module> --format dot | dot -Tsvg > output.svg

Generate PNG:

paracelsus graph <base_path> --import-module <module> --format dot | dot -Tpng > output.png

paracelsus graph example_app.models.base:Base --import-module "example_app.models:*" --format dot | dot -Tsvg > output.svg

Paracelsus can be configured using a [tool.paracelsus] section in your pyproject.toml file. The following keys are supported via the ParacelsusTomlConfig schema:

• base: The base class path (string).
• imports: A list of module strings to import.
• include_tables: A list of specific tables to include in the graph.
• exclude_tables: A list of specific tables to exclude from the graph.
• column_sort: Determines how columns are ordered. Options: key-based (default) or preserve-order.
• omit_comments: Boolean flag to omit comments from the output.
• max_enum_members: Integer limit for enum members to prevent graph bloat (default: 3).
• type_parameter_delimiter: String used to delimit type parameters (default: -).

Mermaid ER diagrams use commas as structural separators. To prevent SQLAlchemy types like NUMERIC(10, 2) from breaking the diagram, Paracelsus replaces commas with a delimiter. The default is a hyphen (-).

You can customize this using --type-parameter-delimiter. Constraint: The delimiter cannot contain commas or spaces.

paracelsus graph example_app.models.base:Base \
  --import-module "example_app.models.users" \
  --type-parameter-delimiter "_"

By default, Paracelsus sorts columns by: Primary Keys $\rightarrow$ Foreign Keys $\rightarrow$ Alphabetical order. Use the --column-sort flag to change this behavior.

Available values:

• key-based (default)
• preserve-order (preserves the order of fields as defined in the SQLAlchemy models)

paracelsus graph example_app.models.base:Base \
  --import-module "example_app.models.users" \
  --column-sort preserve-order

If you do not want to use pyproject.toml, you can use any valid TOML file containing a [tool.paracelsus] section by passing the --config flag to the graph or inject commands.

paracelsus graph --config path/to/alternative_pyproject.toml

You can select a subset of models for your diagram using --include-tables or --exclude-tables. These options are mutually exclusive.

Both options support regular expressions.

# Exclude tables matching a pattern
paracelsus graph example_app.models.base:Base \
  --import-module "example_app.models.*" \
  --exclude-tables "^com.*"

# Include only specific tables
paracelsus graph example_app.models.base:Base \
  --import-module "example_app.models.*" \
  --include-tables "users" \
  --include-tables "posts"

Paracelsus is a CLI application with three primary commands:

• version: Outputs the currently installed version.
• graph: Generates an Entity Relationship Diagram (ERD) and outputs it to stdout.
• inject: Inserts the generated graph into a specified Markdown file.

paracelsus --help