Metadata-Version: 2.4
Name: liquisketch
Version: 0.1.0
Summary: Liquibase in, diagrams out. Sketch your schema from your changelog.
Author-email: Starforge Worker <star.forge.worker@gmail.com>
Maintainer-email: Starforge Worker <star.forge.worker@gmail.com>
Project-URL: Homepage, https://github.com/starforge-universe/liquisketch
Project-URL: Repository, https://github.com/starforge-universe/liquisketch
Project-URL: Bug Tracker, https://github.com/starforge-universe/liquisketch/issues
Keywords: liquibase,schema,diagram,python,liquisketch
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pylint==4.0.5; extra == "dev"
Requires-Dist: coverage==7.13.5; extra == "dev"
Requires-Dist: sphinx==9.0.4; extra == "dev"
Requires-Dist: sphinx-rtd-theme==3.1.0; extra == "dev"
Requires-Dist: build==1.4.3; extra == "dev"
Requires-Dist: twine==6.2.0; extra == "dev"
Requires-Dist: pytest==9.0.3; extra == "dev"
Requires-Dist: pytest-cov==7.1.0; extra == "dev"
Requires-Dist: pytest-mock==3.15.1; extra == "dev"
Dynamic: license-file

# LiquiSketch

Liquibase in, diagrams out - sketch your schema straight from your changelog.

LiquiSketch is a Python utility that reads Liquibase changelogs and produces schema diagrams to help teams understand structure, relationships, and change history.

## Why LiquiSketch

- Keep schema docs aligned with migration history
- Reduce manual diagram maintenance
- Improve onboarding and design reviews
- Catch schema drift earlier

## Quick Start (development)

From a clone of this repository:

```bash
pip install -e ".[dev]"
make check
```

## Installation

### From PyPI

Install the published package (requires Python 3.11+):

```bash
pip install liquisketch
```

This installs the `liquisketch` package and the **`liquisketch`** console script (see [Command line](#command-line)).

### From the GitHub repository

Install the latest default branch without cloning:

```bash
pip install "git+https://github.com/starforge-universe/liquisketch.git"
```

Pin a tag or branch:

```bash
pip install "git+https://github.com/starforge-universe/liquisketch.git@v1.0.1"
pip install "git+https://github.com/starforge-universe/liquisketch.git@main"
```

### Editable install from a local clone

For development, install in editable mode from the repo root:

```bash
git clone https://github.com/starforge-universe/liquisketch.git
cd liquisketch
pip install -e ".[dev]"
```

## Usage

### Command line

After installation, run **`liquisketch`** with two positional arguments:

1. **`CHANGELOG`** — path to your Liquibase **master** changelog XML (for example `changelog-master.xml`).
2. **`OUTPUT`** — path where the Draw.io diagram should be written (for example `schema.drawio`).

```bash
liquisketch path/to/changelog-master.xml path/to/output.drawio
```

Verbose logging (Liquibase parsing and Draw.io sync details):

```bash
liquisketch -v path/to/changelog-master.xml path/to/output.drawio
```

You can also invoke the package as a module (same arguments):

```bash
python -m liquisketch path/to/changelog-master.xml path/to/output.drawio
```

Show help:

```bash
liquisketch --help
```

### Example with the repository test fixture

```bash
liquisketch tests/db/changelog-master.xml tests/db/schema.drawio
```

### Synchronization behavior

- Creates the output file when it does not exist.
- Synchronizes tables, columns, and foreign keys with the changelog-derived schema.
- Removes diagram elements that no longer exist in schema.
- Keeps the original diagram format when updating an existing file:
  - compressed stays compressed
  - uncompressed stays uncompressed
- New files are written as uncompressed Draw.io XML.

### Python API

```python
from pathlib import Path

from liquisketch.drawio import sync_schema_to_drawio
from liquisketch.liquibase import load_database_schema_from_master_changelog

schema = load_database_schema_from_master_changelog(Path("tests/db/changelog-master.xml"))
sync_schema_to_drawio(Path("tests/db/schema.drawio"), schema)
```

## Project Layout

```text
liquisketch/
├── liquisketch/        # Package source
├── tests/              # Test suite
├── pyproject.toml      # Packaging and tooling configuration
├── Makefile            # Development commands
├── CONTRIBUTING.md     # Contributor workflow
└── README.md           # Project overview
```

## Contributing

See `CONTRIBUTING.md` for setup, workflow, and PR expectations.

## License

This project is licensed under `LICENSE`.
