sql-diff-explainer 0.1.0__tar.gz

sql_diff_explainer-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest
+      - run: python -m ruff check .

sql_diff_explainer-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/

sql_diff_explainer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zmodz1010
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sql_diff_explainer-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+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.

sql_diff_explainer-0.1.0/README.md

@@ -0,0 +1,47 @@
+# 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.

sql_diff_explainer-0.1.0/examples/after.sql

@@ -0,0 +1,7 @@
+SELECT department, COUNT(*) AS headcount
+FROM employees
+JOIN departments ON employees.department_id = departments.id
+WHERE active = TRUE
+GROUP BY department
+ORDER BY headcount DESC
+LIMIT 50 OFFSET 10;

sql_diff_explainer-0.1.0/examples/before.sql

@@ -0,0 +1,6 @@
+SELECT department, COUNT(*) AS headcount
+FROM employees
+WHERE active = TRUE
+GROUP BY department
+ORDER BY headcount DESC
+LIMIT 20;

sql_diff_explainer-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sql-diff-explainer"
+version = "0.1.0"
+description = "Explain SQL schema and migration differences"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+  { name = "zmodz1010" },
+]
+dependencies = [
+  "sqlglot>=25.0",
+]
+
+[project.scripts]
+sql-diff-explainer = "sql_diff_explainer.cli:main"
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0",
+  "ruff>=0.6",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sql_diff_explainer"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

sql_diff_explainer-0.1.0/src/sql_diff_explainer/__init__.py

@@ -0,0 +1,26 @@
+"""Tools for explaining SQL query differences."""
+
+from .core import (
+    SQLChange,
+    SQLDiffError,
+    SQLDiffResult,
+    SqlglotParser,
+    SQLParseError,
+    SQLParser,
+    UnsupportedSQL,
+    explain_diff,
+    explain_sql_change,
+)
+
+__all__ = [
+    "SQLChange",
+    "SQLDiffError",
+    "SQLDiffResult",
+    "SQLParseError",
+    "SQLParser",
+    "SqlglotParser",
+    "UnsupportedSQL",
+    "explain_diff",
+    "explain_sql_change",
+]
+__version__ = "0.2.0"

sql_diff_explainer-0.1.0/src/sql_diff_explainer/cli.py

@@ -0,0 +1,47 @@
+"""Command-line interface for SQL Diff Explainer."""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from .core import SQLDiffError, explain_sql_change
+
+
+def main() -> int:
+    """Run the command-line interface."""
+    parser = argparse.ArgumentParser(
+        description="Explain structural differences between two SQL files."
+    )
+    parser.add_argument("before", type=Path, help="Original SQL file")
+    parser.add_argument("after", type=Path, help="Updated SQL file")
+    parser.add_argument("--dialect", help="sqlglot dialect used to parse both files")
+    parser.add_argument("--format", choices=("text", "json"), default="text", dest="output_format")
+    args = parser.parse_args()
+
+    try:
+        result = explain_sql_change(
+            args.before.read_text(encoding="utf-8"),
+            args.after.read_text(encoding="utf-8"),
+            dialect=args.dialect,
+        )
+    except (OSError, SQLDiffError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    if args.output_format == "json":
+        print(json.dumps(result.to_dict(), indent=2))
+    else:
+        print(result.summary)
+        if result.risk_reasons:
+            print(f"Risk: {result.risk.upper()} - {' '.join(result.risk_reasons)}")
+        for change in result.changes:
+            print(f"- [{change.risk.upper()}] {change.description}")
+            if change.before is not None:
+                print(f"  before: {change.before}")
+            if change.after is not None:
+                print(f"  after:  {change.after}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

sql_diff_explainer-0.1.0/src/sql_diff_explainer/core.py

@@ -0,0 +1,277 @@
+"""SQL-aware query comparison and risk classification."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections import Counter
+from dataclasses import dataclass, field
+from difflib import unified_diff
+from typing import Any
+
+
+class SQLDiffError(ValueError):
+    """Base class for expected SQL diff errors."""
+
+
+class SQLParseError(SQLDiffError):
+    """Raised when either SQL document cannot be parsed."""
+
+
+class UnsupportedSQL(SQLDiffError):
+    """Raised when the parsed statements are not supported query statements."""
+
+
+class SQLParser(ABC):
+    """Abstract parser boundary, allowing another SQL parser to be plugged in."""
+
+    @abstractmethod
+    def parse(self, sql: str, dialect: str | None = None) -> Any:
+        """Parse one SQL statement and return the parser's syntax tree."""
+
+
+class SqlglotParser(SQLParser):
+    """Parser implementation backed by sqlglot."""
+
+    def parse(self, sql: str, dialect: str | None = None) -> Any:
+        try:
+            import sqlglot
+            from sqlglot import exp
+        except ImportError as exc:  # pragma: no cover - dependency is declared
+            raise SQLParseError("sqlglot is required to parse SQL") from exc
+
+        if not sql.strip():
+            raise SQLParseError("SQL input is empty")
+        try:
+            tree = sqlglot.parse_one(sql, read=dialect or None)
+        except Exception as exc:
+            raise SQLParseError(f"Unable to parse SQL: {exc}") from exc
+        if not isinstance(tree, exp.Query):
+            raise UnsupportedSQL(
+                f"Only SELECT queries are supported (received {tree.__class__.__name__})"
+            )
+        return tree
+
+
+@dataclass(frozen=True)
+class SQLChange:
+    """One semantic change found between two query trees."""
+
+    category: str
+    description: str
+    before: str | None
+    after: str | None
+    risk: str
+
+    def to_dict(self) -> dict[str, str | None]:
+        return {
+            "category": self.category,
+            "description": self.description,
+            "before": self.before,
+            "after": self.after,
+            "risk": self.risk,
+        }
+
+
+@dataclass
+class SQLDiffResult:
+    """Structured explanation returned by :func:`explain_sql_change`."""
+
+    changes: list[SQLChange] = field(default_factory=list)
+    risk: str = "low"
+    risk_reasons: list[str] = field(default_factory=list)
+    dialect: str | None = None
+
+    @property
+    def summary(self) -> str:
+        if not self.changes:
+            return "No structural SQL changes detected."
+        return f"{len(self.changes)} SQL change(s) detected; overall risk is {self.risk}."
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "summary": self.summary,
+            "risk": self.risk,
+            "risk_reasons": list(self.risk_reasons),
+            "dialect": self.dialect,
+            "changes": [change.to_dict() for change in self.changes],
+        }
+
+
+def _sql(node: Any, dialect: str | None) -> str | None:
+    if node is None:
+        return None
+    if isinstance(node, bool):
+        return str(node).lower()
+    if isinstance(node, (int, float, str)):
+        return str(node)
+    return node.sql(dialect=dialect or None)
+
+
+def _values(select: Any, key: str, dialect: str | None) -> list[str]:
+    value = select.args.get(key)
+    if value is None:
+        return []
+    if key == "group":
+        expressions = value.expressions
+    elif key == "order":
+        expressions = value.expressions
+    else:
+        expressions = [value.this]
+    return [_sql(expression, dialect) or "" for expression in expressions]
+
+
+def _select_expression(tree: Any) -> Any:
+    from sqlglot import exp
+
+    select = tree if isinstance(tree, exp.Select) else tree.find(exp.Select)
+    if select is None:
+        raise UnsupportedSQL("Only SELECT queries are supported")
+    return select
+
+
+def _features(tree: Any, dialect: str | None) -> dict[str, list[str] | str | bool | None]:
+    from sqlglot import exp
+
+    select = _select_expression(tree)
+    projections = [_sql(expression, dialect) or "" for expression in select.expressions]
+    joins = [_sql(join, dialect) or "" for join in select.args.get("joins", [])]
+    aggregations = sorted(
+        {_sql(node, dialect) or "" for node in select.find_all(exp.AggFunc)}
+    )
+    where = select.args.get("where")
+    return {
+        "select": projections,
+        "joins": joins,
+        "where": _sql(where.this if where else None, dialect),
+        "group_by": _values(select, "group", dialect),
+        "aggregation": aggregations,
+        "order_by": _values(select, "order", dialect),
+        "limit": _sql(
+            (
+                select.args.get("limit").expression
+                if select.args.get("limit")
+                else None
+            ),
+            dialect,
+        ),
+        "offset": _sql(
+            select.args.get("offset").expression if select.args.get("offset") else None,
+            dialect,
+        ),
+        "distinct": bool(select.args.get("distinct")),
+    }
+
+
+_RISK = {
+    "removed_where": ("high", "Removing a WHERE predicate can expand the result set."),
+    "removed_join": ("high", "Removing a JOIN can change row matching and cardinality."),
+    "aggregation": ("high", "Changing aggregation can alter result meaning and cardinality."),
+    "select": ("medium", "Changing projected columns changes the result shape."),
+    "group_by": ("high", "Changing GROUP BY changes result granularity."),
+    "distinct": ("medium", "Changing DISTINCT can introduce or remove duplicate rows."),
+    "order_by": ("low", "Changing ORDER BY changes result ordering."),
+    "limit": ("medium", "Changing LIMIT changes the number of returned rows."),
+    "offset": ("medium", "Changing OFFSET changes which rows are returned."),
+    "where": ("medium", "Changing a WHERE predicate changes which rows qualify."),
+    "join": ("medium", "Changing a JOIN can change row matching or cardinality."),
+}
+
+
+def _change(
+    category: str,
+    before: Any,
+    after: Any,
+    dialect: str | None,
+) -> SQLChange:
+    before_text = before if isinstance(before, str) or before is None else _sql(before, dialect)
+    after_text = after if isinstance(after, str) or after is None else _sql(after, dialect)
+    key = "removed_" + category if after_text is None else category
+    risk = _RISK.get(key, ("medium", f"{category.title()} changed."))[0]
+    action = "removed" if after_text is None else "changed" if before_text else "added"
+    return SQLChange(
+        category=category,
+        description=f"{category.replace('_', ' ').title()} {action}.",
+        before=before_text,
+        after=after_text,
+        risk=risk,
+    )
+
+
+def _sequence_changes(
+    category: str,
+    before: list[str],
+    after: list[str],
+    dialect: str | None,
+) -> list[SQLChange]:
+    changes: list[SQLChange] = []
+    if Counter(before) == Counter(after):
+        return changes
+    removed = list((Counter(before) - Counter(after)).elements())
+    added = list((Counter(after) - Counter(before)).elements())
+    for value in removed:
+        changes.append(_change(category, value, None, dialect))
+    for value in added:
+        changes.append(_change(category, None, value, dialect))
+    return changes
+
+
+def explain_sql_change(
+    before: str,
+    after: str,
+    *,
+    dialect: str | None = None,
+    parser: SQLParser | None = None,
+) -> SQLDiffResult:
+    """Explain structural changes between two SELECT queries."""
+    parser = parser or SqlglotParser()
+    before_tree = parser.parse(before, dialect)
+    after_tree = parser.parse(after, dialect)
+    before_features = _features(before_tree, dialect)
+    after_features = _features(after_tree, dialect)
+    changes: list[SQLChange] = []
+
+    sequence_categories = ("select", "joins", "group_by", "aggregation", "order_by")
+    for category in sequence_categories:
+        before_values = before_features[category]
+        after_values = after_features[category]
+        if not isinstance(before_values, list) or not isinstance(after_values, list):
+            raise UnsupportedSQL(f"Unable to compare {category}")
+        changes.extend(
+            _sequence_changes(
+                category.removesuffix("s"),
+                before_values,
+                after_values,
+                dialect,
+            )
+        )
+    for category in ("where", "limit", "offset", "distinct"):
+        if before_features[category] != after_features[category]:
+            changes.append(
+                _change(category, before_features[category], after_features[category], dialect)
+            )
+
+    reasons: list[str] = []
+    severity = {"low": 0, "medium": 1, "high": 2}
+    overall = "low"
+    for change in changes:
+        if severity[change.risk] > severity[overall]:
+            overall = change.risk
+        reason = _RISK.get(
+            ("removed_" + change.category if change.after is None else change.category),
+            ("medium", ""),
+        )[1]
+        if reason and reason not in reasons:
+            reasons.append(reason)
+    return SQLDiffResult(changes=changes, risk=overall, risk_reasons=reasons, dialect=dialect)
+
+
+def explain_diff(before: str, after: str) -> str:
+    """Return a readable unified diff for two SQL documents."""
+    lines = unified_diff(
+        before.splitlines(),
+        after.splitlines(),
+        fromfile="before.sql",
+        tofile="after.sql",
+        lineterm="",
+    )
+    return "\n".join(lines)

sql_diff_explainer-0.1.0/tests/test_core.py

@@ -0,0 +1,64 @@
+import pytest
+
+from sql_diff_explainer import SQLParseError, UnsupportedSQL, explain_diff, explain_sql_change
+
+
+def test_explain_diff_returns_unified_diff() -> None:
+    result = explain_diff("CREATE TABLE users;", "CREATE TABLE accounts;")
+
+    assert "--- before.sql" in result
+    assert "+++ after.sql" in result
+    assert "-CREATE TABLE users;" in result
+    assert "+CREATE TABLE accounts;" in result
+
+
+def test_explain_sql_change_detects_core_query_features() -> None:
+    before = (
+        "SELECT DISTINCT a, COUNT(*) FROM users u WHERE active = 1 "
+        "GROUP BY a ORDER BY a LIMIT 10"
+    )
+    after = (
+        "SELECT a, SUM(amount) FROM users u JOIN orders o ON u.id = o.user_id "
+        "WHERE active = 1 AND region = 'EU' GROUP BY a ORDER BY a DESC LIMIT 20 OFFSET 5"
+    )
+
+    result = explain_sql_change(before, after)
+    categories = {change.category for change in result.changes}
+
+    assert {"select", "join", "aggregation", "distinct", "limit", "offset"}.issubset(categories)
+    assert result.risk == "high"
+    assert result.to_dict()["changes"]
+
+
+def test_explain_sql_change_reports_filter_removal_as_high_risk() -> None:
+    result = explain_sql_change(
+        "SELECT id FROM users WHERE active = TRUE",
+        "SELECT id FROM users",
+    )
+
+    assert result.risk == "high"
+    assert any(change.category == "where" and change.risk == "high" for change in result.changes)
+
+
+def test_explain_sql_change_accepts_dialect() -> None:
+    result = explain_sql_change(
+        "SELECT TOP 5 id FROM users",
+        "SELECT TOP 10 id FROM users",
+        dialect="tsql",
+    )
+
+    assert result.changes[0].category == "limit"
+
+
+def test_parse_and_unsupported_errors_are_clean() -> None:
+    with pytest.raises(SQLParseError):
+        explain_sql_change("SELECT FROM", "SELECT 1")
+    with pytest.raises(UnsupportedSQL):
+        explain_sql_change("CREATE TABLE users (id INT)", "SELECT 1")
+
+
+def test_identical_queries_have_no_changes() -> None:
+    result = explain_sql_change("SELECT id FROM users", "SELECT id FROM users")
+
+    assert result.changes == []
+    assert result.risk == "low"