sql-diff-explainer 0.1.0__py3-none-any.whl → 0.1.2__py3-none-any.whl

sql_diff_explainer/__init__.py

@@ -23,4 +23,4 @@ __all__ = [
     "explain_diff",
     "explain_sql_change",
 ]
-__version__ = "0.2.0"
+__version__ = "0.1.2"

sql_diff_explainer/cli.py

@@ -7,6 +7,8 @@ from pathlib import Path
 
 from .core import SQLDiffError, explain_sql_change
 
+_RISK_SEVERITY = {"low": 0, "medium": 1, "high": 2}
+
 
 def main() -> int:
     """Run the command-line interface."""
@@ -17,6 +19,11 @@ def main() -> int:
     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")
+    parser.add_argument(
+        "--fail-on-risk",
+        choices=tuple(_RISK_SEVERITY),
+        help="Exit with status 1 when detected risk meets or exceeds this level",
+    )
     args = parser.parse_args()
 
     try:
@@ -40,6 +47,12 @@ def main() -> int:
                 print(f"  before: {change.before}")
             if change.after is not None:
                 print(f"  after:  {change.after}")
+    if (
+        args.fail_on_risk is not None
+        and result.changes
+        and _RISK_SEVERITY[result.risk] >= _RISK_SEVERITY[args.fail_on_risk]
+    ):
+        return 1
     return 0
 
 

sql_diff_explainer/core.py

@@ -81,6 +81,11 @@ class SQLDiffResult:
     risk_reasons: list[str] = field(default_factory=list)
     dialect: str | None = None
 
+    @property
+    def risk_level(self) -> str:
+        """Backward-compatible alias for the overall risk classification."""
+        return self.risk
+
     @property
     def summary(self) -> str:
         if not self.changes:
@@ -91,6 +96,7 @@ class SQLDiffResult:
         return {
             "summary": self.summary,
             "risk": self.risk,
+            "risk_level": self.risk_level,
             "risk_reasons": list(self.risk_reasons),
             "dialect": self.dialect,
             "changes": [change.to_dict() for change in self.changes],
@@ -129,12 +135,24 @@ def _select_expression(tree: Any) -> Any:
     return select
 
 
-def _features(tree: Any, dialect: str | None) -> dict[str, list[str] | str | bool | None]:
+def _join_values(select: Any, dialect: str | None) -> list[tuple[str, str]]:
+    joins = []
+    for join in select.args.get("joins", []):
+        side = (join.args.get("side") or "INNER").upper()
+        target = _sql(join.args.get("this"), dialect) or ""
+        condition = _sql(join.args.get("on"), dialect) or ""
+        joins.append((f"{target} ON {condition}", f"{side} JOIN {target} ON {condition}"))
+    return joins
+
+
+def _features(
+    tree: Any, dialect: str | None
+) -> dict[str, list[str] | list[tuple[str, 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", [])]
+    joins = _join_values(select, dialect)
     aggregations = sorted(
         {_sql(node, dialect) or "" for node in select.find_all(exp.AggFunc)}
     )
@@ -174,6 +192,10 @@ _RISK = {
     "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."),
+    "join_type": (
+        "high",
+        "Changing an outer JOIN to INNER JOIN can exclude unmatched rows.",
+    ),
 }
 
 
@@ -182,10 +204,11 @@ def _change(
     before: Any,
     after: Any,
     dialect: str | None,
+    risk_key: str | None = 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
+    key = risk_key or ("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(
@@ -215,6 +238,48 @@ def _sequence_changes(
     return changes
 
 
+def _join_changes(
+    before: list[tuple[str, str]],
+    after: list[tuple[str, str]],
+    dialect: str | None,
+) -> list[SQLChange]:
+    """Pair joins by target and predicate so join-type changes stay semantic."""
+    before_by_signature = Counter(signature for signature, _ in before)
+    after_by_signature = Counter(signature for signature, _ in after)
+    changes: list[SQLChange] = []
+    for signature in before_by_signature.keys() & after_by_signature.keys():
+        before_rendered = [rendered for item, rendered in before if item == signature]
+        after_rendered = [rendered for item, rendered in after if item == signature]
+        for before_rendered_value, after_rendered_value in zip(
+            before_rendered, after_rendered, strict=True
+        ):
+            if before_rendered_value != after_rendered_value:
+                changes.append(
+                    _change(
+                        "join",
+                        before_rendered_value,
+                        after_rendered_value,
+                        dialect,
+                        risk_key=(
+                            "join_type"
+                            if before_rendered_value.split(" ", 1)[0].upper()
+                            in {"LEFT", "RIGHT", "FULL"}
+                            and after_rendered_value.split(" ", 1)[0].upper() == "INNER"
+                            else None
+                        ),
+                    )
+                )
+    removed = list((before_by_signature - after_by_signature).elements())
+    added = list((after_by_signature - before_by_signature).elements())
+    for signature in removed:
+        rendered = next(rendered for item, rendered in before if item == signature)
+        changes.append(_change("join", rendered, None, dialect))
+    for signature in added:
+        rendered = next(rendered for item, rendered in after if item == signature)
+        changes.append(_change("join", None, rendered, dialect))
+    return changes
+
+
 def explain_sql_change(
     before: str,
     after: str,
@@ -230,7 +295,13 @@ def explain_sql_change(
     after_features = _features(after_tree, dialect)
     changes: list[SQLChange] = []
 
-    sequence_categories = ("select", "joins", "group_by", "aggregation", "order_by")
+    before_joins = before_features["joins"]
+    after_joins = after_features["joins"]
+    if not isinstance(before_joins, list) or not isinstance(after_joins, list):
+        raise UnsupportedSQL("Unable to compare joins")
+    changes.extend(_join_changes(before_joins, after_joins, dialect))
+
+    sequence_categories = ("select", "group_by", "aggregation", "order_by")
     for category in sequence_categories:
         before_values = before_features[category]
         after_values = after_features[category]
@@ -256,8 +327,19 @@ def explain_sql_change(
     for change in changes:
         if severity[change.risk] > severity[overall]:
             overall = change.risk
+        join_type_change = (
+            change.category == "join"
+            and change.before is not None
+            and change.after is not None
+            and change.before.split(" ", 1)[0].upper() in {"LEFT", "RIGHT", "FULL"}
+            and change.after.split(" ", 1)[0].upper() == "INNER"
+        )
         reason = _RISK.get(
-            ("removed_" + change.category if change.after is None else change.category),
+            (
+                "join_type"
+                if join_type_change
+                else ("removed_" + change.category if change.after is None else change.category)
+            ),
             ("medium", ""),
         )[1]
         if reason and reason not in reasons:

sql_diff_explainer-0.1.2.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.5
+Name: sql-diff-explainer
+Version: 0.1.2
+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.
+
+The next patch release is **0.1.2**. It adds the CI-friendly CLI
+`--fail-on-risk` threshold.
+
+## Why use SQL Diff Explainer?
+
+Use it in a pull request, migration review, or CI check when a textual SQL diff
+does not explain the behavioral impact of a query change. It is especially
+useful for data-engineering teams reviewing:
+
+- dbt model changes where a join or filter can change row counts
+- warehouse reports where grouping or aggregation changes the grain
+- incremental pipeline queries where `DISTINCT`, `ORDER BY`, `LIMIT`, or
+  `OFFSET` changes the records consumed downstream
+- generated SQL changes where normalized syntax is easier to compare than
+  formatting or alias changes
+
+The result is a structured object, so a CI integration can fail or annotate a
+review based on `result.risk_level`, inspect `result.changes`, or serialize
+`result.to_dict()` as JSON.
+
+## Real-life data-engineering examples
+
+The `examples/` directory contains runnable before/after pairs. For example:
+
+```powershell
+sql-diff-explainer examples\join_before.sql examples\join_after.sql
+sql-diff-explainer examples\filter_before.sql examples\filter_after.sql --format json
+sql-diff-explainer examples\aggregation_before.sql examples\aggregation_after.sql
+sql-diff-explainer examples\distinct_before.sql examples\distinct_after.sql
+```
+
+These scenarios demonstrate the changes reviewers most often need to discuss:
+
+1. **Outer join to inner join:** changing `LEFT JOIN` to `INNER JOIN` can
+   exclude dimension or fact rows without a match, so the tool reports one
+   semantic join change at high risk.
+2. **Added `WHERE` filter:** adding `WHERE order_status = 'completed'` narrows
+   the population and is reported as a filter change.
+3. **Aggregation or grouping change:** changing `COUNT(*)` to `SUM(revenue)`,
+   or changing the `GROUP BY` grain from customer to customer and day, can
+   change metric meaning and row cardinality.
+4. **`DISTINCT`, ordering, and pagination:** adding `DISTINCT` changes duplicate
+   handling; changing `ORDER BY` changes presentation or deterministic paging;
+   changing `LIMIT`/`OFFSET` changes which rows a downstream consumer receives.
+
+Try the same comparisons from Python:
+
+```python
+from sql_diff_explainer import explain_sql_change
+
+result = explain_sql_change(
+    "SELECT c.id FROM customers c LEFT JOIN orders o ON c.id = o.customer_id",
+    "SELECT c.id FROM customers c INNER JOIN orders o ON c.id = o.customer_id",
+)
+assert result.risk_level == "high"
+for change in result.changes:
+    print(change.category, change.risk, change.description)
+```
+
+## What it catches—and what it cannot know
+
+The analyzer parses both inputs with sqlglot and compares the supported
+`SELECT` structure: projections, joins and join types, `WHERE`, `GROUP BY`,
+aggregate functions, `ORDER BY`, `LIMIT`, `OFFSET`, and `DISTINCT`. It provides
+static risk guidance; it does not execute SQL or connect to a warehouse.
+
+Risk is therefore a useful review signal, not a correctness proof. The tool
+cannot infer table statistics, actual null rates, constraints, query plans,
+cost, freshness, permissions, dialect-specific UDF behavior, or whether a
+business metric is correct. It also does not validate schema availability or
+compare multiple statements in a migration file. Pair its output with
+warehouse tests, representative row-count checks, query-plan review, and
+domain-owner approval.
+
+## 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
+sql-diff-explainer before.sql after.sql --fail-on-risk medium
+sql-diff-explainer before.sql after.sql --format json --fail-on-risk high
+```
+
+`--fail-on-risk` accepts `low`, `medium`, or `high` and exits with status 1 when
+detected overall risk meets or exceeds the chosen threshold. It does not suppress
+the regular text or JSON report. Comparisons with no detected changes exit
+successfully even though their baseline report risk is `low`. JSON output is
+intended for CI and integrations; text output is optimized for human review.
+
+Exit codes:
+
+- `0`: the comparison succeeded and no detected change met the configured
+  threshold (or `--fail-on-risk` was not set).
+- `1`: detected overall risk met or exceeded `--fail-on-risk`.
+- `2`: an input file could not be read or an expected SQL parse/support error
+  occurred.

sql_diff_explainer-0.1.2.dist-info/RECORD

@@ -0,0 +1,8 @@
+sql_diff_explainer/__init__.py,sha256=P-jgWkLNkeuM1kcLChW7rSYWn6EpqOY8K0qMvALxqyA,488
+sql_diff_explainer/cli.py,sha256=XNYIVozEXbjJa_1PXX6ZYmgqxmqHkLHAYNuKaovMCJI,2091
+sql_diff_explainer/core.py,sha256=P9NrPjHGivx-sGlyIyVi7V41x4R2lH3ETC4y8opz_yQ,13265
+sql_diff_explainer-0.1.2.dist-info/METADATA,sha256=0UOgvJOzI3j8gbI64wGVOq1YkGKkNNajipAEGyYJjL4,5863
+sql_diff_explainer-0.1.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+sql_diff_explainer-0.1.2.dist-info/entry_points.txt,sha256=Pu2gG46es25JExzGO58plyLEsFedeCUM-TQnUeLpOlI,67
+sql_diff_explainer-0.1.2.dist-info/licenses/LICENSE,sha256=OJ2eEuGmpMxVb7jSmuVgeDcVHCEOMBkZgLgTlnK5mQQ,1087
+sql_diff_explainer-0.1.2.dist-info/RECORD,,

sql_diff_explainer-0.1.0.dist-info/METADATA

@@ -1,61 +0,0 @@
-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.dist-info/RECORD

@@ -1,8 +0,0 @@
-sql_diff_explainer/__init__.py,sha256=LBftz-d21IFEViSlfMu38LlnNRdr0iZzwLJj97134f8,488
-sql_diff_explainer/cli.py,sha256=pRgyrCD6bzPpMjOSSJSTZVF_D3Nj4w71cnvPvP6T1DM,1672
-sql_diff_explainer/core.py,sha256=exD3WeAy1cbrmw1Y-JLO7DrPs5yJelsZU2MdD7gzV1E,9733
-sql_diff_explainer-0.1.0.dist-info/METADATA,sha256=uMT9bJJ_PJLWaMzyGje_psBrq-YNhZpdsmB_oCSvhc4,1818
-sql_diff_explainer-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-sql_diff_explainer-0.1.0.dist-info/entry_points.txt,sha256=Pu2gG46es25JExzGO58plyLEsFedeCUM-TQnUeLpOlI,67
-sql_diff_explainer-0.1.0.dist-info/licenses/LICENSE,sha256=OJ2eEuGmpMxVb7jSmuVgeDcVHCEOMBkZgLgTlnK5mQQ,1087
-sql_diff_explainer-0.1.0.dist-info/RECORD,,