Metadata-Version: 2.5
Name: sql-diff-explainer
Version: 0.1.0
Summary: Explain SQL schema and migration differences
Author: zmodz1010
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: sqlglot>=25.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# SQL Diff Explainer

Explain the meaningful structural differences between two SQL `SELECT` queries.

The package uses [sqlglot](https://github.com/tobymao/sqlglot) behind an abstract
parser interface, so callers receive a stable result even if the parser
implementation changes. It reports changes to projections, joins, filters,
grouping, aggregation, ordering, pagination, and `DISTINCT`, with a static
low/medium/high risk classification.

## Development

This project uses a `src/` layout and requires Python 3.10 or newer.

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
pytest
```

## Library usage

```python
from sql_diff_explainer import explain_sql_change

result = explain_sql_change(
    "SELECT department, COUNT(*) FROM employees GROUP BY department",
    "SELECT department, COUNT(*) FROM employees WHERE active = TRUE GROUP BY department",
)
print(result.to_dict())
```

`explain_sql_change` raises `SQLParseError` for invalid SQL and `UnsupportedSQL`
for non-`SELECT` statements. Pass `dialect="postgres"` (or another sqlglot
dialect) when parsing dialect-specific syntax.

## CLI

```powershell
sql-diff-explainer before.sql after.sql
sql-diff-explainer before.sql after.sql --dialect postgres --format json
```

JSON output is intended for CI and integrations; text output is optimized for
human review. The process exits with status 2 for unreadable files or expected
SQL errors.
