sql-diff-explainer 0.1.1__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.1.1"
+__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-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.1.dist-info/METADATA

@@ -1,65 +0,0 @@
-Metadata-Version: 2.5
-Name: sql-diff-explainer
-Version: 0.1.1
-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 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.
-
-```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.1.dist-info/RECORD

@@ -1,8 +0,0 @@
-sql_diff_explainer/__init__.py,sha256=n-nvklsRpRpqafOg6dZtPE5yJ3uh9r54BLzaa9xx0_Y,488
-sql_diff_explainer/cli.py,sha256=pRgyrCD6bzPpMjOSSJSTZVF_D3Nj4w71cnvPvP6T1DM,1672
-sql_diff_explainer/core.py,sha256=P9NrPjHGivx-sGlyIyVi7V41x4R2lH3ETC4y8opz_yQ,13265
-sql_diff_explainer-0.1.1.dist-info/METADATA,sha256=LG0recDF171dnNC1qplkMuYxBvGwdm3ng0yHC8KQlBI,2009
-sql_diff_explainer-0.1.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-sql_diff_explainer-0.1.1.dist-info/entry_points.txt,sha256=Pu2gG46es25JExzGO58plyLEsFedeCUM-TQnUeLpOlI,67
-sql_diff_explainer-0.1.1.dist-info/licenses/LICENSE,sha256=OJ2eEuGmpMxVb7jSmuVgeDcVHCEOMBkZgLgTlnK5mQQ,1087
-sql_diff_explainer-0.1.1.dist-info/RECORD,,