sqlassert-dbt 0.3.1__tar.gz

sqlassert_dbt-0.3.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fred Israel
+
+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.

sqlassert_dbt-0.3.1/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: sqlassert-dbt
+Version: 0.3.1
+Summary: Check a dbt project's tests and sqlassert markers from its compiled manifest.
+Author: Fred Israel
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/polvoazul/sqlassert/tree/main/integrations/dbt
+Project-URL: Issues, https://github.com/polvoazul/sqlassert/issues
+Keywords: dbt,sql,static-analysis,data-quality,sqlassert
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: sqlassert
+Requires-Dist: sqlglot<31,>=30.30
+Provides-Extra: test
+Requires-Dist: dbt-core>=1.12; extra == "test"
+Requires-Dist: dbt-duckdb>=1.11; extra == "test"
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# sqlassert-dbt
+
+Prove your dbt tests from the SQL, and skip the ones that can't fail.
+
+A `unique` or `not_null` test scans a table in the warehouse on every run, and
+it only tells you about today's data. Many of those tests follow from the SQL
+itself: `customer_id` is unique because the model groups by it, `status` is
+never null because of a `coalesce`. [sqlassert](https://github.com/polvoazul/sqlassert)
+proves them from the compiled model before anything runs, so dbt can leave them
+out: faster CI, a smaller warehouse bill, and the same guarantee for *any*
+data, not just the rows there today.
+
+```bash
+pip install sqlassert-dbt
+```
+
+_Alpha: the markers and dbt test mappings are stable; the CLI output may
+change._
+
+## Skip the tests the SQL proves
+
+Run dbt through the plugin:
+
+```bash
+sqlassert-dbt build . -- --target prod    # or: sqlassert-dbt test
+```
+
+It runs `dbt compile`, checks every model, then runs `dbt build` (or
+`dbt test`) with each proved test passed as `--exclude`. Arguments after `--`
+go to dbt unchanged. The exit code is dbt's when dbt fails, otherwise the
+check's.
+
+The tests of the sources, seeds and models a model reads are trusted as
+facts, since `dbt build` runs them first in the same invocation. If the
+arguments after `--` select nodes (`--select`, `--exclude`, `--selector`, ...),
+an upstream test may not run, so none is trusted.
+
+## Check without dbt
+
+`check` reads only `target/manifest.json`, so dbt does not need to be installed
+where it runs (a CI step after `dbt compile`, say):
+
+```bash
+$ dbt compile
+$ sqlassert-dbt check . --trust-upstream-tests
+models/customers.sql:12: UNKNOWN /**ASSERT NOT NULL(first_name)**/ (customers)
+
+Proved statically (a test here can be skipped):
+  models/schema.yml  unique_stg_customers_customer_id  (test on stg_customers)
+
+Not proved (the warehouse run still checks these):
+  models/schema.yml  accepted_values_stg_orders_status__placed__shipped__returned  (test on stg_orders): its Property is not proved from the SQL
+
+Proved but untested (schema.yml additions):
+  models/schema.yml  customers.customer_id: not_null
+```
+
+Three lists come out:
+
+- **Proved statically:** tests the SQL already guarantees. Skip them.
+- **Not proved:** tests that still need the warehouse. Nothing is wrong; the
+  SQL alone can't show the property.
+- **Proved but untested:** properties sqlassert proved that no test states.
+  Free `schema.yml` additions, which cost nothing to keep.
+
+| Option | |
+|---|---|
+| `--trust-upstream-tests` | Treat passing tests of upstream nodes as facts (true under `dbt build`). Without it, a `dbt-untrusted-upstream-tests` warning lists them. |
+| `--require-proved` | Fail when any test is not proved, not only when a marker is `UNKNOWN`. |
+| `--explain` | Print each proof, and each failed proof. |
+| `--dialect NAME` | Analyze under this dialect instead of the adapter's. |
+| `--manifest PATH` | Read another manifest (default `PROJECT/target/manifest.json`). |
+
+Exit codes: `0` every marker proved; `1` a marker is `UNKNOWN` or an error was
+reported (unproved tests fail it only with `--require-proved`); `2` the
+manifest cannot be read.
+
+## What it understands
+
+| dbt | sqlassert Property |
+|---|---|
+| `unique` | Unique Set |
+| `not_null` | Not Null |
+| `accepted_values` | Enum |
+| `relationships` | Referential Coverage (Foreign Key) |
+| `dbt_utils.unique_combination_of_columns` | Non-Null Unique Set (it counts NULL equal to NULL) |
+| contract `primary_key`, `unique`, `not_null`, `foreign_key` | the same Properties |
+
+A model's own tests are what gets proved. Upstream tests are evidence, used
+only when they fail on any failing row: not a test with `severity: warn`, a
+`where:` config, or `error_if`/`fail_calc` thresholds. A constraint counts only
+on a contracted table whose adapter enforces it.
+
+## Markers in models
+
+You can also write sqlassert markers straight into a model, and they are checked
+and reported at their line in the model file:
+
+```sql
+-- models/customer_orders.sql
+select c.customer_id, c.first_name, o.order_id
+from {{ ref('stg_orders') }} o
+/**ASSERT MANY TO ONE**/ join {{ ref('stg_customers') }} c
+  on o.customer_id = c.customer_id
+```
+
+If someone later loads duplicate customers upstream, or drops the `unique`
+test that made this provable, the marker turns `UNKNOWN` and CI fails before
+the join fans out in production. See the
+[sqlassert README](https://github.com/polvoazul/sqlassert#readme) for every
+marker.
+
+## Details
+
+- **Manifest:** only the latest schema (v12, written by dbt 1.8 to 1.12).
+- **Ephemeral models** are analyzed where dbt inlined them.
+- **Incremental models** are analyzed in both `is_incremental()` branches. A
+  test holds only if it holds in both, and a key only under a `merge` or
+  `delete+insert` strategy on that `unique_key` with no
+  `incremental_predicates`. The other branch is rendered without dbt only when
+  the model uses `ref`, `source`, `this`, `config` and `is_incremental()`
+  alone; otherwise it is reported unanalyzed.
+- **Adapters:** analyzed when sqlassert models their dialect (DuckDB,
+  PostgreSQL, MySQL, Snowflake, BigQuery, Databricks / Spark, Redshift, Trino).
+- A model with markers but no compiled code is an error, not skipped.
+
+## License
+
+MIT

sqlassert_dbt-0.3.1/README.md

@@ -0,0 +1,129 @@
+# sqlassert-dbt
+
+Prove your dbt tests from the SQL, and skip the ones that can't fail.
+
+A `unique` or `not_null` test scans a table in the warehouse on every run, and
+it only tells you about today's data. Many of those tests follow from the SQL
+itself: `customer_id` is unique because the model groups by it, `status` is
+never null because of a `coalesce`. [sqlassert](https://github.com/polvoazul/sqlassert)
+proves them from the compiled model before anything runs, so dbt can leave them
+out: faster CI, a smaller warehouse bill, and the same guarantee for *any*
+data, not just the rows there today.
+
+```bash
+pip install sqlassert-dbt
+```
+
+_Alpha: the markers and dbt test mappings are stable; the CLI output may
+change._
+
+## Skip the tests the SQL proves
+
+Run dbt through the plugin:
+
+```bash
+sqlassert-dbt build . -- --target prod    # or: sqlassert-dbt test
+```
+
+It runs `dbt compile`, checks every model, then runs `dbt build` (or
+`dbt test`) with each proved test passed as `--exclude`. Arguments after `--`
+go to dbt unchanged. The exit code is dbt's when dbt fails, otherwise the
+check's.
+
+The tests of the sources, seeds and models a model reads are trusted as
+facts, since `dbt build` runs them first in the same invocation. If the
+arguments after `--` select nodes (`--select`, `--exclude`, `--selector`, ...),
+an upstream test may not run, so none is trusted.
+
+## Check without dbt
+
+`check` reads only `target/manifest.json`, so dbt does not need to be installed
+where it runs (a CI step after `dbt compile`, say):
+
+```bash
+$ dbt compile
+$ sqlassert-dbt check . --trust-upstream-tests
+models/customers.sql:12: UNKNOWN /**ASSERT NOT NULL(first_name)**/ (customers)
+
+Proved statically (a test here can be skipped):
+  models/schema.yml  unique_stg_customers_customer_id  (test on stg_customers)
+
+Not proved (the warehouse run still checks these):
+  models/schema.yml  accepted_values_stg_orders_status__placed__shipped__returned  (test on stg_orders): its Property is not proved from the SQL
+
+Proved but untested (schema.yml additions):
+  models/schema.yml  customers.customer_id: not_null
+```
+
+Three lists come out:
+
+- **Proved statically:** tests the SQL already guarantees. Skip them.
+- **Not proved:** tests that still need the warehouse. Nothing is wrong; the
+  SQL alone can't show the property.
+- **Proved but untested:** properties sqlassert proved that no test states.
+  Free `schema.yml` additions, which cost nothing to keep.
+
+| Option | |
+|---|---|
+| `--trust-upstream-tests` | Treat passing tests of upstream nodes as facts (true under `dbt build`). Without it, a `dbt-untrusted-upstream-tests` warning lists them. |
+| `--require-proved` | Fail when any test is not proved, not only when a marker is `UNKNOWN`. |
+| `--explain` | Print each proof, and each failed proof. |
+| `--dialect NAME` | Analyze under this dialect instead of the adapter's. |
+| `--manifest PATH` | Read another manifest (default `PROJECT/target/manifest.json`). |
+
+Exit codes: `0` every marker proved; `1` a marker is `UNKNOWN` or an error was
+reported (unproved tests fail it only with `--require-proved`); `2` the
+manifest cannot be read.
+
+## What it understands
+
+| dbt | sqlassert Property |
+|---|---|
+| `unique` | Unique Set |
+| `not_null` | Not Null |
+| `accepted_values` | Enum |
+| `relationships` | Referential Coverage (Foreign Key) |
+| `dbt_utils.unique_combination_of_columns` | Non-Null Unique Set (it counts NULL equal to NULL) |
+| contract `primary_key`, `unique`, `not_null`, `foreign_key` | the same Properties |
+
+A model's own tests are what gets proved. Upstream tests are evidence, used
+only when they fail on any failing row: not a test with `severity: warn`, a
+`where:` config, or `error_if`/`fail_calc` thresholds. A constraint counts only
+on a contracted table whose adapter enforces it.
+
+## Markers in models
+
+You can also write sqlassert markers straight into a model, and they are checked
+and reported at their line in the model file:
+
+```sql
+-- models/customer_orders.sql
+select c.customer_id, c.first_name, o.order_id
+from {{ ref('stg_orders') }} o
+/**ASSERT MANY TO ONE**/ join {{ ref('stg_customers') }} c
+  on o.customer_id = c.customer_id
+```
+
+If someone later loads duplicate customers upstream, or drops the `unique`
+test that made this provable, the marker turns `UNKNOWN` and CI fails before
+the join fans out in production. See the
+[sqlassert README](https://github.com/polvoazul/sqlassert#readme) for every
+marker.
+
+## Details
+
+- **Manifest:** only the latest schema (v12, written by dbt 1.8 to 1.12).
+- **Ephemeral models** are analyzed where dbt inlined them.
+- **Incremental models** are analyzed in both `is_incremental()` branches. A
+  test holds only if it holds in both, and a key only under a `merge` or
+  `delete+insert` strategy on that `unique_key` with no
+  `incremental_predicates`. The other branch is rendered without dbt only when
+  the model uses `ref`, `source`, `this`, `config` and `is_incremental()`
+  alone; otherwise it is reported unanalyzed.
+- **Adapters:** analyzed when sqlassert models their dialect (DuckDB,
+  PostgreSQL, MySQL, Snowflake, BigQuery, Databricks / Spark, Redshift, Trino).
+- A model with markers but no compiled code is an error, not skipped.
+
+## License
+
+MIT

sqlassert_dbt-0.3.1/pyproject.toml

@@ -0,0 +1,58 @@
+[build-system]
+requires = ["setuptools>=77", "setuptools-scm>=8"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sqlassert-dbt"
+dynamic = ["version"]
+description = "Check a dbt project's tests and sqlassert markers from its compiled manifest."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Fred Israel" }]
+requires-python = ">=3.13"
+keywords = ["dbt", "sql", "static-analysis", "data-quality", "sqlassert"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Database",
+  "Topic :: Software Development :: Quality Assurance",
+]
+# Reads target/manifest.json only: dbt itself is needed to compile the
+# project, not to check it, so it is a test dependency here.
+dependencies = [
+  "sqlassert",
+  "sqlglot>=30.30,<31",
+]
+
+[project.urls]
+Homepage = "https://github.com/polvoazul/sqlassert/tree/main/integrations/dbt"
+Issues = "https://github.com/polvoazul/sqlassert/issues"
+
+[project.scripts]
+sqlassert-dbt = "sqlassert_dbt.__main__:main"
+
+[project.optional-dependencies]
+test = [
+  "dbt-core>=1.12",
+  "dbt-duckdb>=1.11",
+  "pytest",
+]
+
+[tool.setuptools.packages.find]
+include = ["sqlassert_dbt", "sqlassert_dbt.*"]
+
+[tool.setuptools_scm]
+root = "../.."
+local_scheme = "no-local-version"
+
+# In this repository the plugin builds and tests against the sibling sqlassert.
+[tool.uv.sources]
+sqlassert = { path = "../..", editable = true }
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "../.."]
+
+[tool.ty.environment]
+extra-paths = ["../.."]

sqlassert_dbt-0.3.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sqlassert_dbt-0.3.1/sqlassert_dbt/__init__.py

@@ -0,0 +1,19 @@
+"""dbt integration: check a dbt project's tests and Property Markers from its manifest, without dbt.
+
+`analyze_project(project_dir)` reads `target/manifest.json` and returns a
+`DbtReport`: which tests the SQL proves (skippable), which it does not, which
+proved Properties no test states, and the outcome of every marker written in
+a model file, mapped back to that file's lines. `sqlassert-dbt` is its command
+line (`__main__.py`).
+"""
+
+from sqlassert_dbt.project import SUPPORTED_DIALECTS, ProjectError, analyze_project
+from sqlassert_dbt.report import (
+    DbtReport, Location, MarkerOutcome, Problem, Status, TestOutcome, Untested,
+    exit_code, format_text,
+)
+
+__all__ = [
+    "SUPPORTED_DIALECTS", "DbtReport", "Location", "MarkerOutcome", "Problem",
+    "ProjectError", "Status", "TestOutcome", "Untested", "analyze_project", "exit_code", "format_text",
+]

sqlassert_dbt-0.3.1/sqlassert_dbt/__main__.py

@@ -0,0 +1,115 @@
+"""Command line.
+
+`sqlassert-dbt check [PROJECT]` checks a compiled dbt project's tests and
+markers from its `target/manifest.json`, with `sqlassert check`'s exit codes.
+
+`sqlassert-dbt build|test [PROJECT] [-- DBT_ARGS]` runs dbt with the markers
+checked too: `dbt compile`, then the check, then `dbt build` (or `dbt test`)
+with every test the SQL proves excluded. dbt runs the tests of what a model
+reads in the same invocation, so they are facts, unless DBT_ARGS select nodes
+(a selection may leave an upstream test out).
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from sqlassert.check import EXIT_FINDINGS, EXIT_OK, EXIT_USAGE
+from sqlassert_dbt.project import ProjectError, analyze_project
+from sqlassert_dbt.report import DbtReport, exit_code, format_text
+
+# The dbt flags that narrow which nodes run: under any of them, the tests of
+# what a model reads may not run, so they are no facts.
+SELECTION_FLAGS = frozenset({"-s", "--select", "-m", "--models", "--model", "--exclude", "--selector", "--resource-type", "--resource-types"})
+
+
+def run_dbt(arguments: list[str]) -> int:
+    """Run dbt from PATH with `arguments`; its exit status."""
+    try:
+        return subprocess.run(["dbt", *arguments], check=False).returncode
+    except FileNotFoundError:
+        print("sqlassert-dbt: dbt is not on PATH", file=sys.stderr)
+        return EXIT_USAGE
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="sqlassert-dbt")
+    commands = parser.add_subparsers(dest="command", required=True)
+    check = commands.add_parser(
+        "check",
+        help="check the tests and markers of a compiled project, without dbt",
+        description="Check a dbt project's tests and markers from its target/manifest.json (run `dbt compile` first). "
+        f"Exit status: {EXIT_OK} every marker PROVED, {EXIT_FINDINGS} a marker UNKNOWN or a diagnostic reported, "
+        f"{EXIT_USAGE} the manifest cannot be read.",
+    )
+    _common(check)
+    check.add_argument("--manifest", help="manifest.json to read (default: PROJECT/target/manifest.json)")
+    check.add_argument(
+        "--trust-upstream-tests", action="store_true",
+        help="take the passing tests of what each model reads as facts about it: true when they run first, as in `dbt build`",
+    )
+    for name, verb in (("build", "dbt build"), ("test", "dbt test")):
+        command = commands.add_parser(
+            name,
+            help=f"`dbt compile`, check the markers, then `{verb}` without the tests the SQL proves",
+            description=f"Run `dbt compile`, check the project, then `{verb}` excluding every test the SQL proves. "
+            f"Arguments after -- go to dbt. Exit status: dbt's when it fails, else {EXIT_FINDINGS} when a marker is "
+            f"UNKNOWN or a diagnostic is reported, else {EXIT_OK}.",
+        )
+        _common(command)
+        command.add_argument("dbt_arguments", nargs=argparse.REMAINDER, help="-- then arguments for dbt")
+    arguments = parser.parse_args(argv)
+    project = Path(arguments.project)
+
+    if arguments.command == "check":
+        report = _analyze(project, arguments.manifest, arguments.dialect, arguments.trust_upstream_tests)
+        if report is None:
+            return EXIT_USAGE
+        sys.stdout.write(format_text(report, explain=arguments.explain))
+        return exit_code(report, require_proved=arguments.require_proved)
+
+    passed = [argument for argument in arguments.dbt_arguments if argument != "--"]
+    located = [*passed, "--project-dir", str(project)]
+    compiled = run_dbt(["compile", *located])
+    if compiled != 0:
+        return compiled
+    selecting = any(argument.split("=")[0] in SELECTION_FLAGS for argument in passed)
+    report = _analyze(project, None, arguments.dialect, not selecting)
+    if report is None:
+        return EXIT_USAGE
+    sys.stdout.write(format_text(report, explain=arguments.explain))
+    proved = proved_tests(report)
+    ran = run_dbt([arguments.command, *located, *(["--exclude", *proved] if proved else [])])
+    return ran if ran != 0 else exit_code(report, require_proved=arguments.require_proved)
+
+
+def _common(command: argparse.ArgumentParser) -> None:
+    command.add_argument("project", nargs="?", default=".", help="dbt project directory (default: .)")
+    command.add_argument("--dialect", help="analyze under this dialect instead of the adapter's")
+    command.add_argument("--explain", action="store_true", help="print each proof and failed proof")
+    command.add_argument(
+        "--require-proved", action="store_true",
+        help=f"exit {EXIT_FINDINGS} when a dbt test is not proved from the SQL, too, not only a marker",
+    )
+
+
+def proved_tests(report: DbtReport) -> list[str]:
+    """The names of the tests the SQL proves, to pass dbt as `--exclude`."""
+    return sorted({test.name for test in report.tests if test.skippable})
+
+
+def _analyze(project: Path, manifest: str | None, dialect: str | None, trust: bool) -> DbtReport | None:
+    try:
+        return analyze_project(
+            project, manifest_path=Path(manifest) if manifest else None, dialect=dialect, trust_upstream_tests=trust,
+        )
+    except ProjectError as error:
+        print(f"sqlassert-dbt: {error}", file=sys.stderr)
+        return None
+
+
+if __name__ == "__main__":
+    sys.exit(main())