SQL Diff Explainer

Explain the meaningful structural differences between two SQL SELECT queries.

The package uses 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.

The current patch release is 0.1.1. It includes the stable risk_level compatibility property, semantic join-type pairing, and high-risk classification for outer-to-inner join changes.

Development

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

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

Library usage

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

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.