sqlassert 0.1.2__py3-none-any.whl → 0.3.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sqlassert/__init__.py +34 -9
- sqlassert/__main__.py +138 -0
- sqlassert/check.py +444 -0
- sqlassert/diagnostics.py +57 -0
- sqlassert/dialects.py +211 -0
- sqlassert/discovery/__init__.py +30 -0
- sqlassert/discovery/bigquery.py +71 -0
- sqlassert/discovery/databricks.py +18 -0
- sqlassert/discovery/duckdb.py +163 -0
- sqlassert/discovery/fetcher.py +402 -0
- sqlassert/discovery/information_schema.py +326 -0
- sqlassert/discovery/mysql.py +70 -0
- sqlassert/discovery/postgres.py +143 -0
- sqlassert/discovery/redshift.py +36 -0
- sqlassert/discovery/snowflake.py +63 -0
- sqlassert/discovery/trino.py +37 -0
- sqlassert/improvements.py +528 -0
- sqlassert/ir/__init__.py +56 -0
- sqlassert/ir/convert.py +2377 -0
- sqlassert/ir/model.py +676 -0
- sqlassert/main.py +57 -0
- sqlassert/properties.py +121 -0
- sqlassert/provenance.py +73 -0
- sqlassert/python_engine.py +299 -0
- sqlassert/reporting.py +102 -0
- sqlassert/rules/STYLEGUIDE.md +19 -0
- sqlassert/rules/__init__.py +11 -0
- sqlassert/rules/column_set.py +34 -0
- sqlassert/rules/domain.py +376 -0
- sqlassert/rules/equality.py +233 -0
- sqlassert/rules/exactly_one.py +75 -0
- sqlassert/rules/foreign_key.py +316 -0
- sqlassert/rules/join_cardinality.py +94 -0
- sqlassert/rules/nullability.py +418 -0
- sqlassert/rules/uniqueness.py +601 -0
- sqlassert/smells.py +306 -0
- sqlassert/sql_parse.py +974 -0
- sqlassert/suggest.py +339 -0
- sqlassert-0.3.1.dist-info/METADATA +725 -0
- sqlassert-0.3.1.dist-info/RECORD +44 -0
- {sqlassert-0.1.2.dist-info → sqlassert-0.3.1.dist-info}/WHEEL +1 -1
- sqlassert-0.3.1.dist-info/entry_points.txt +2 -0
- sqlassert-0.3.1.dist-info/licenses/LICENSE +21 -0
- sqlassert/unique.py +0 -605
- sqlassert-0.1.2.dist-info/METADATA +0 -173
- sqlassert-0.1.2.dist-info/RECORD +0 -6
- {sqlassert-0.1.2.dist-info → sqlassert-0.3.1.dist-info}/top_level.txt +0 -0
sqlassert/main.py
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
"""Compose parsing, IR conversion, and property analysis into a Report."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from dataclasses import replace
|
|
6
|
+
from typing import TYPE_CHECKING
|
|
7
|
+
|
|
8
|
+
from sqlassert import diagnostics as diag
|
|
9
|
+
from sqlassert.ir.convert import IrParser
|
|
10
|
+
from sqlassert.python_engine import Engine
|
|
11
|
+
from sqlassert.reporting import Report
|
|
12
|
+
from sqlassert.sql_parse import SqlParser
|
|
13
|
+
|
|
14
|
+
if TYPE_CHECKING:
|
|
15
|
+
from sqlassert.discovery import DatabaseKnowledgeFetcher
|
|
16
|
+
|
|
17
|
+
DEFAULT_DIALECT = "duckdb"
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def analyze(sql: str, *, dialect: str = DEFAULT_DIALECT, trust_unenforced_keys: bool = True) -> Report:
|
|
21
|
+
"""Prove the Unique Join Assertions and Unique Set Assertions in one SQL Program.
|
|
22
|
+
|
|
23
|
+
Pure: the Program is the only source of Knowledge. `analyze_database`
|
|
24
|
+
adds a database catalog. Where a catalog would have helped (a table with
|
|
25
|
+
no `CREATE`, a column only a catalog can resolve), the Report warns.
|
|
26
|
+
`trust_unenforced_keys` (on by default) makes the keys the dialect does
|
|
27
|
+
not enforce Property Declarations, as `RELY` does; off, they are ignored
|
|
28
|
+
with an `unenforced-constraint` warning (`docs/dialects.md`).
|
|
29
|
+
"""
|
|
30
|
+
sql_parser = SqlParser(dialect)
|
|
31
|
+
ir_parser = IrParser(dialect, trust_unenforced_keys)
|
|
32
|
+
|
|
33
|
+
ast = sql_parser.parse(sql)
|
|
34
|
+
conversion = ir_parser.parse(ast)
|
|
35
|
+
diagnostics = ast.diagnostics + conversion.diagnostics
|
|
36
|
+
return Engine().run(conversion.program, conversion.knowledge, diagnostics, conversion.warnings)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def analyze_database(
|
|
40
|
+
sql: str, fetcher: DatabaseKnowledgeFetcher, *, dialect: str = DEFAULT_DIALECT, trust_unenforced_keys: bool = True,
|
|
41
|
+
) -> Report:
|
|
42
|
+
"""`analyze`, with the external Relations the Program reaches hydrated from a catalog.
|
|
43
|
+
|
|
44
|
+
The fetcher reads catalog metadata only, never rows, and binds it to the
|
|
45
|
+
final IR before the engine runs once. No connection warnings: a relation
|
|
46
|
+
the catalog lacks is already a diagnostic. A catalog key the dialect does
|
|
47
|
+
not enforce warns, unless `trust_unenforced_keys` declares it, and so do
|
|
48
|
+
the SQL's own warnings (`diagnostics.SQL_WARNINGS`).
|
|
49
|
+
"""
|
|
50
|
+
ast = SqlParser(dialect).parse(sql)
|
|
51
|
+
hydration = fetcher.hydrate(ast, dialect=dialect, trust_unenforced_keys=trust_unenforced_keys)
|
|
52
|
+
conversion = hydration.conversion
|
|
53
|
+
facts = fetcher.bind(conversion.program, hydration)
|
|
54
|
+
program = replace(conversion.program, declarations=conversion.program.declarations + facts.declarations)
|
|
55
|
+
diagnostics = ast.diagnostics + hydration.diagnostics + conversion.diagnostics
|
|
56
|
+
warnings = (*facts.warnings, *(warning for warning in conversion.warnings if warning.code in diag.SQL_WARNINGS))
|
|
57
|
+
return Engine().run(program, conversion.knowledge + facts.knowledge, diagnostics, warnings)
|
sqlassert/properties.py
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
"""Structural properties over the relational IR."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from sqlassert.ir.model import Join, LiteralValue, NodeMeta, OutputColumn, SimpleCase
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class Property(metaclass=NodeMeta, abstract=True):
|
|
9
|
+
"""One semantic statement, independent of how it enters reasoning."""
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class NonNullColumn(Property):
|
|
13
|
+
column: OutputColumn
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class NonNullColumns(Property):
|
|
17
|
+
"""Every listed column is non-null: one assertion for a whole column list."""
|
|
18
|
+
|
|
19
|
+
columns: frozenset[OutputColumn]
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class NonNullElements(Property):
|
|
23
|
+
"""No listed column's value has a NULL element: an ARRAY's elements, a
|
|
24
|
+
ROW's fields, a MAP's values, nested ones included (`NOT NULL ELEMENTS`).
|
|
25
|
+
Says nothing of the value itself, which may be NULL. No catalog states it,
|
|
26
|
+
so it is only asserted or declared."""
|
|
27
|
+
|
|
28
|
+
columns: frozenset[OutputColumn]
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class UniqueSet(Property):
|
|
32
|
+
columns: frozenset[OutputColumn]
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
class NonNullUniqueSet(UniqueSet):
|
|
36
|
+
"""A Unique Set whose columns are all non-null."""
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class FunctionalDependency(Property):
|
|
40
|
+
"""Rows agreeing on every `determinant` column, all non-null, agree on
|
|
41
|
+
every `dependent` column (`DETERMINES`). Lax: NULL in the determinant
|
|
42
|
+
exempts a row, as it does for a Unique Set."""
|
|
43
|
+
|
|
44
|
+
determinant: frozenset[OutputColumn]
|
|
45
|
+
dependent: frozenset[OutputColumn]
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
class EnumeratedDomain(Property):
|
|
49
|
+
"""Every non-null value of `column` is one of `values`.
|
|
50
|
+
|
|
51
|
+
NULL is outside every domain (`NOT NULL` governs it), and a domain does
|
|
52
|
+
not claim that each of its values occurs.
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
column: OutputColumn
|
|
56
|
+
values: frozenset[LiteralValue]
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
class ExhaustiveCase(Property):
|
|
60
|
+
"""Every member of `case`'s operand's Enumerated Domain has a WHEN arm
|
|
61
|
+
that is exactly that literal, so no non-null operand value reaches ELSE.
|
|
62
|
+
|
|
63
|
+
ELSE never substitutes for an arm, and a NULL operand, which matches no
|
|
64
|
+
arm, is left to `NOT NULL`.
|
|
65
|
+
"""
|
|
66
|
+
|
|
67
|
+
case: SimpleCase
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
class ManyToOneJoin(Property):
|
|
71
|
+
"""A join that cannot repeat a row of its left input: each left row
|
|
72
|
+
matches at most one right row (`MANY TO ONE`)."""
|
|
73
|
+
|
|
74
|
+
join: Join
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
class OneToManyJoin(Property):
|
|
78
|
+
"""A join that cannot repeat a row of its right input: each right row
|
|
79
|
+
matches at most one left row (`ONE TO MANY`)."""
|
|
80
|
+
|
|
81
|
+
join: Join
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
class OneToOneJoin(Property):
|
|
85
|
+
"""A join that repeats a row of neither input (`ONE TO ONE`)."""
|
|
86
|
+
|
|
87
|
+
join: Join
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
class UniqueJoin(Property):
|
|
91
|
+
"""A join that repeats rows of at most one input: it is not many to many
|
|
92
|
+
(`UNIQUE`, `NOT MANY TO MANY`)."""
|
|
93
|
+
|
|
94
|
+
join: Join
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
class ExactlyOneJoin(Property):
|
|
98
|
+
"""A join in which every row of its left input matches exactly one right row.
|
|
99
|
+
|
|
100
|
+
The join neither multiplies nor removes left rows, and a left join
|
|
101
|
+
null-extends none of them.
|
|
102
|
+
"""
|
|
103
|
+
|
|
104
|
+
join: Join
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
class ReferentialCoverage(Property):
|
|
108
|
+
"""Every row whose referencing columns are all non-null has a row of the
|
|
109
|
+
referenced relation equal to it on the paired referenced columns.
|
|
110
|
+
|
|
111
|
+
Columns pair by position. A row with a null referencing component is exempt
|
|
112
|
+
(`MATCH SIMPLE`). This is the part of a Foreign Key that Knowledge supplies:
|
|
113
|
+
`REFERENCES` constraints, catalog foreign keys, and declarations.
|
|
114
|
+
"""
|
|
115
|
+
|
|
116
|
+
columns: tuple[OutputColumn, ...]
|
|
117
|
+
referenced_columns: tuple[OutputColumn, ...]
|
|
118
|
+
|
|
119
|
+
|
|
120
|
+
class ForeignKey(ReferentialCoverage):
|
|
121
|
+
"""Referential Coverage onto a Unique Set of the referenced relation."""
|
sqlassert/provenance.py
ADDED
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
"""Source locations for semantic elements and diagnostics.
|
|
2
|
+
|
|
3
|
+
Origins hold plain values so that no SQLGlot node or connection can escape
|
|
4
|
+
through reporting.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
SQL = "sql"
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
@dataclass(frozen=True, order=True)
|
|
16
|
+
class Span:
|
|
17
|
+
"""A region of SQL text: where a Property Marker is written. Spans order by position.
|
|
18
|
+
|
|
19
|
+
Lines and columns count from 1, columns in characters; `end_column` is
|
|
20
|
+
one past the region's last character, as SARIF's `endColumn`.
|
|
21
|
+
"""
|
|
22
|
+
|
|
23
|
+
line: int
|
|
24
|
+
column: int
|
|
25
|
+
end_line: int
|
|
26
|
+
end_column: int
|
|
27
|
+
|
|
28
|
+
@classmethod
|
|
29
|
+
def of(cls, sql: str, start: int, end: int) -> Span:
|
|
30
|
+
"""The region of `sql[start:end]`."""
|
|
31
|
+
line, column = _position(sql, start)
|
|
32
|
+
end_line, end_column = _position(sql, end)
|
|
33
|
+
return cls(line, column, end_line, end_column)
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _position(sql: str, offset: int) -> tuple[int, int]:
|
|
37
|
+
return sql.count("\n", 0, offset) + 1, offset - sql.rfind("\n", 0, offset)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
@dataclass(frozen=True)
|
|
41
|
+
class Origin:
|
|
42
|
+
"""A SQL source span or catalog fact that a semantic element arose from.
|
|
43
|
+
|
|
44
|
+
`line` is the first source line, when known; `span` the exact region,
|
|
45
|
+
when the element is a Property Marker (its `line` is then `line`).
|
|
46
|
+
"""
|
|
47
|
+
|
|
48
|
+
kind: str
|
|
49
|
+
detail: str
|
|
50
|
+
line: int | None = None
|
|
51
|
+
span: Span | None = None
|
|
52
|
+
|
|
53
|
+
@classmethod
|
|
54
|
+
def marked(cls, detail: str, span: Span) -> Origin:
|
|
55
|
+
"""The Origin of something a Property Marker at `span` asserts or reports."""
|
|
56
|
+
return cls(SQL, detail, span.line, span)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
@dataclass(frozen=True)
|
|
60
|
+
class AttachmentSite:
|
|
61
|
+
"""Where a Property Marker for one JOIN or Select Expression is written.
|
|
62
|
+
|
|
63
|
+
`offset` indexes the SQL text: a join marker is inserted there, before the
|
|
64
|
+
join's first keyword; a trailing column marker is appended there, after
|
|
65
|
+
the Select Expression's last token. `label` names what the site marks
|
|
66
|
+
(`JOIN users AS u`, `view v`, `CTE c`, `subquery s`, `Root Select`);
|
|
67
|
+
anonymous Select Expressions share a label and are told apart by `line`.
|
|
68
|
+
"""
|
|
69
|
+
|
|
70
|
+
label: str
|
|
71
|
+
line: int
|
|
72
|
+
offset: int
|
|
73
|
+
trailing: bool
|
|
@@ -0,0 +1,299 @@
|
|
|
1
|
+
"""Analysis-scoped memoization and evidence for Python property functions."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from collections.abc import Generator, Iterable, Iterator
|
|
6
|
+
from contextlib import contextmanager
|
|
7
|
+
from contextvars import ContextVar
|
|
8
|
+
from dataclasses import dataclass, field, fields
|
|
9
|
+
from enum import IntEnum
|
|
10
|
+
from functools import wraps
|
|
11
|
+
from inspect import signature
|
|
12
|
+
|
|
13
|
+
from case_conversion import snake
|
|
14
|
+
|
|
15
|
+
from sqlassert import ir
|
|
16
|
+
from sqlassert.diagnostics import DUPLICATE_DECLARATION, Diagnostic
|
|
17
|
+
from sqlassert.properties import Property
|
|
18
|
+
from sqlassert.reporting import ASSERTED_KINDS, AssertionReport, Outcome, RelationFacts, Report
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@dataclass(eq=False)
|
|
22
|
+
class Result[T]:
|
|
23
|
+
"""A property function's value and evidence, including collection members."""
|
|
24
|
+
|
|
25
|
+
value: T
|
|
26
|
+
reason: str
|
|
27
|
+
subjects: tuple[object, ...] = ()
|
|
28
|
+
premises: list[Result] = field(default_factory=list)
|
|
29
|
+
kind: str = "structural"
|
|
30
|
+
members: dict = field(default_factory=dict)
|
|
31
|
+
|
|
32
|
+
def __bool__(self) -> bool:
|
|
33
|
+
raise TypeError("Use .value to inspect a result, or & and | to compose Boolean evidence")
|
|
34
|
+
|
|
35
|
+
def __and__(self: Result[bool], other: Result[bool]) -> Result[bool]:
|
|
36
|
+
return all_of((self, other))
|
|
37
|
+
|
|
38
|
+
def __or__(self: Result[bool], other: Result[bool]) -> Result[bool]:
|
|
39
|
+
return any_of((self, other))
|
|
40
|
+
|
|
41
|
+
def explain(self) -> str:
|
|
42
|
+
"""Render the evidence, referring back to shared premises by number."""
|
|
43
|
+
lines: list[str] = []
|
|
44
|
+
seen: dict[Result, int] = {}
|
|
45
|
+
|
|
46
|
+
def visit(result: Result, depth: int) -> None:
|
|
47
|
+
indent = " " * depth
|
|
48
|
+
if result in seen:
|
|
49
|
+
lines.append(f"{indent}see #{seen[result]}")
|
|
50
|
+
return
|
|
51
|
+
seen[result] = len(seen) + 1
|
|
52
|
+
match result.value:
|
|
53
|
+
case True:
|
|
54
|
+
state = "PROVED"
|
|
55
|
+
case False:
|
|
56
|
+
state = "UNKNOWN"
|
|
57
|
+
case _:
|
|
58
|
+
state = "VALUE"
|
|
59
|
+
locations = []
|
|
60
|
+
for subject in result.subjects:
|
|
61
|
+
match subject:
|
|
62
|
+
case ir.Node(origin=origin):
|
|
63
|
+
locations.append(origin)
|
|
64
|
+
case _:
|
|
65
|
+
pass # Property arguments may also be sets and other plain values.
|
|
66
|
+
sources = "; ".join(
|
|
67
|
+
f"{origin.detail}" + (f" (line {origin.line})" if origin.line is not None else "")
|
|
68
|
+
for origin in dict.fromkeys(locations)
|
|
69
|
+
)
|
|
70
|
+
suffix = f" — {sources}" if sources else ""
|
|
71
|
+
lines.append(f"{indent}#{seen[result]} {state}: {result.reason}{suffix}")
|
|
72
|
+
for premise in result.premises:
|
|
73
|
+
visit(premise, depth + 1)
|
|
74
|
+
|
|
75
|
+
visit(self, 0)
|
|
76
|
+
return "\n".join(lines)
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def unknown(reason: str, *subjects: object) -> Result[bool]:
|
|
80
|
+
return Result(False, reason, subjects, kind="unknown")
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def all_of(results: Iterable[Result[bool]]) -> Result[bool]:
|
|
84
|
+
premises = list(results)
|
|
85
|
+
return Result(all(_boolean_values(premises)), "All premises required", premises=premises, kind="all")
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def any_of(results: Iterable[Result[bool]]) -> Result[bool]:
|
|
89
|
+
premises = list(results)
|
|
90
|
+
return Result(any(_boolean_values(premises)), "Any alternative suffices", premises=premises, kind="any")
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def _boolean_values(results):
|
|
94
|
+
values = []
|
|
95
|
+
for result in results:
|
|
96
|
+
match result.value:
|
|
97
|
+
case True | False:
|
|
98
|
+
values.append(result.value)
|
|
99
|
+
case _:
|
|
100
|
+
raise TypeError("Boolean composition requires Result[bool]")
|
|
101
|
+
return values
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
_active: ContextVar[Arena] = ContextVar("property_analysis")
|
|
105
|
+
analysis_functions = []
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def cache(function):
|
|
109
|
+
"""Memoize only within the active analysis, using normalized arguments."""
|
|
110
|
+
parameters = signature(function)
|
|
111
|
+
|
|
112
|
+
@wraps(function)
|
|
113
|
+
def cached(*args, **kwargs):
|
|
114
|
+
arena = current_arena()
|
|
115
|
+
bound = parameters.bind(*args, **kwargs)
|
|
116
|
+
bound.apply_defaults()
|
|
117
|
+
key = (function, tuple(bound.arguments.values()))
|
|
118
|
+
if key in arena.cache:
|
|
119
|
+
return arena.cache[key]
|
|
120
|
+
if key in arena.evaluating:
|
|
121
|
+
raise RuntimeError(
|
|
122
|
+
f"cyclic property dependency: {cached.__name__}. This is an internal sqlassert bug, "
|
|
123
|
+
"not a problem with the analyzed SQL: an analysis broke the Stratum order"
|
|
124
|
+
)
|
|
125
|
+
arena.evaluating.add(key)
|
|
126
|
+
try:
|
|
127
|
+
result = function(*args, **kwargs)
|
|
128
|
+
arena.cache[key] = result
|
|
129
|
+
return result
|
|
130
|
+
finally:
|
|
131
|
+
arena.evaluating.remove(key)
|
|
132
|
+
|
|
133
|
+
return cached
|
|
134
|
+
|
|
135
|
+
|
|
136
|
+
class Stratum(IntEnum):
|
|
137
|
+
"""The order in which facts about one relation may use each other.
|
|
138
|
+
|
|
139
|
+
An analysis about relation R may use any fact about R's inputs, but facts
|
|
140
|
+
about R itself only at its own or a lower stratum. The IR's relations form a
|
|
141
|
+
DAG, so this keeps the whole call graph acyclic: the memoized engine cannot
|
|
142
|
+
compute mutually recursive facts, which would need a fixpoint.
|
|
143
|
+
|
|
144
|
+
Equality groups come first: they read only the relation's own conjuncts
|
|
145
|
+
and its inputs' groups. Unique Joins (and Exactly One Joins) follow, so a
|
|
146
|
+
relation's Null Sources may use them; dependencies use Null Sources (a padded side's
|
|
147
|
+
dependencies hold only when the join cannot pad an agreeing row) and Unique
|
|
148
|
+
Joins; closure uses dependencies and non-nullness; Unique Sets and
|
|
149
|
+
Functional Dependency assertions are closure questions; Foreign Keys use
|
|
150
|
+
Unique Sets. Enumerated Domains come last: they read equality groups and,
|
|
151
|
+
for a CASE's unreachable ELSE, non-nullness. A cycle is an internal sqlassert bug, not a problem
|
|
152
|
+
with the analyzed SQL.
|
|
153
|
+
"""
|
|
154
|
+
|
|
155
|
+
EQUALITY_GROUP = 5
|
|
156
|
+
UNIQUE_JOIN = 10
|
|
157
|
+
NON_NULL = 20
|
|
158
|
+
FUNCTIONAL_DEPENDENCY = 30
|
|
159
|
+
CLOSURE = 40
|
|
160
|
+
UNIQUE_SET = 50
|
|
161
|
+
FOREIGN_KEY = 60
|
|
162
|
+
DOMAIN = 70
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def analysis(stratum: Stratum):
|
|
166
|
+
"""Cache and name an analysis function; public ones match Property names and fields."""
|
|
167
|
+
|
|
168
|
+
def decorate(function):
|
|
169
|
+
parameters = signature(function)
|
|
170
|
+
|
|
171
|
+
@cache
|
|
172
|
+
@wraps(function)
|
|
173
|
+
def evaluate(*args, **kwargs):
|
|
174
|
+
bound = parameters.bind(*args, **kwargs)
|
|
175
|
+
bound.apply_defaults()
|
|
176
|
+
arena = current_arena()
|
|
177
|
+
relation = _subject_relation(arena.program, bound.arguments.values())
|
|
178
|
+
if relation is not None:
|
|
179
|
+
for active, active_stratum, name in arena.active:
|
|
180
|
+
assert active is not relation or stratum <= active_stratum, (
|
|
181
|
+
f"{function.__name__} ({stratum.name}) called from {name} ({active_stratum.name}) "
|
|
182
|
+
"about the same relation: a fact may only use facts at its own or a lower stratum"
|
|
183
|
+
)
|
|
184
|
+
arena.active.append((relation, stratum, function.__name__))
|
|
185
|
+
try:
|
|
186
|
+
arguments = tuple(sorted(bound.arguments.items()))
|
|
187
|
+
accepted = arena.accepted.get((function.__name__, arguments), ())
|
|
188
|
+
result = any_of(accepted) if accepted else function(*args, **kwargs)
|
|
189
|
+
finally:
|
|
190
|
+
arena.active.pop()
|
|
191
|
+
return Result(result.value, function.__name__, tuple(bound.arguments.values()), [result], "claim", result.members)
|
|
192
|
+
|
|
193
|
+
evaluate.stratum = stratum
|
|
194
|
+
analysis_functions.append(evaluate)
|
|
195
|
+
return evaluate
|
|
196
|
+
|
|
197
|
+
return decorate
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
def _subject_relation(program: ir.Program, arguments: Iterable[object]) -> ir.RelationExpr | None:
|
|
201
|
+
"""The relation an analysis call is about: its first argument that names one."""
|
|
202
|
+
for argument in arguments:
|
|
203
|
+
match argument:
|
|
204
|
+
case ir.RelationExpr():
|
|
205
|
+
return argument
|
|
206
|
+
case ir.OutputColumn():
|
|
207
|
+
return program.column_to_parent_relation_index.get(argument)
|
|
208
|
+
case frozenset() | tuple():
|
|
209
|
+
return program.relation_of(frozenset(argument))
|
|
210
|
+
case Result(value=value) if isinstance(getattr(value, "relation", None), ir.RelationExpr):
|
|
211
|
+
return value.relation
|
|
212
|
+
case _:
|
|
213
|
+
pass # Scalar expressions and plain values are not about one relation.
|
|
214
|
+
return None
|
|
215
|
+
|
|
216
|
+
|
|
217
|
+
def current_arena() -> Arena:
|
|
218
|
+
return _active.get()
|
|
219
|
+
|
|
220
|
+
|
|
221
|
+
class Arena:
|
|
222
|
+
"""One immutable program's knowledge, memoized values, and evidence graph."""
|
|
223
|
+
|
|
224
|
+
def __init__(self, program: ir.Program, knowledge: tuple[Property, ...]):
|
|
225
|
+
self.cache: dict[tuple, object] = {}
|
|
226
|
+
self.evaluating: set[tuple] = set()
|
|
227
|
+
self.active: list[tuple[ir.RelationExpr | None, Stratum, str]] = []
|
|
228
|
+
self.accepted: dict[tuple, tuple[Result[bool], ...]] = {}
|
|
229
|
+
self.program = program
|
|
230
|
+
self.knowledge = (*knowledge, *program.declarations)
|
|
231
|
+
# Schema Knowledge is accepted; Property Declarations are the author's trusted claims.
|
|
232
|
+
sources = [("Accepted", item) for item in knowledge] + [("Declared", item) for item in program.declarations]
|
|
233
|
+
for label, item in sources:
|
|
234
|
+
values = tuple(getattr(item, field.name) for field in fields(item))
|
|
235
|
+
subjects = []
|
|
236
|
+
for value in values:
|
|
237
|
+
match value:
|
|
238
|
+
case frozenset() | set() | list() | tuple():
|
|
239
|
+
subjects.extend(value)
|
|
240
|
+
case _:
|
|
241
|
+
subjects.append(value)
|
|
242
|
+
evidence = Result(True, f"{label} {type(item).__name__}", (item, *subjects), kind="accepted")
|
|
243
|
+
for cls in Property._subclasses:
|
|
244
|
+
if cls not in type(item).__mro__:
|
|
245
|
+
continue
|
|
246
|
+
key = _accepted_key(cls, item)
|
|
247
|
+
self.accepted[key] = (*self.accepted.get(key, ()), evidence)
|
|
248
|
+
|
|
249
|
+
def accepted_evidence(self, item: Property) -> tuple[Result[bool], ...]:
|
|
250
|
+
"""The evidence accepting `item` as Knowledge, empty when it is not."""
|
|
251
|
+
return self.accepted.get(_accepted_key(type(item), item), ())
|
|
252
|
+
|
|
253
|
+
def prove(self, property: Property) -> Result[bool]:
|
|
254
|
+
values = {field.name: getattr(property, field.name) for field in fields(property)}
|
|
255
|
+
evaluator, = (function for function in analysis_functions if function.__name__ == snake(type(property).__name__))
|
|
256
|
+
return evaluator(**values)
|
|
257
|
+
|
|
258
|
+
|
|
259
|
+
def _accepted_key(cls: type[Property], item: Property) -> tuple:
|
|
260
|
+
"""How `item`, as an instance of `cls`, is looked up among accepted results."""
|
|
261
|
+
return (snake(cls.__name__), tuple(sorted((field.name, getattr(item, field.name)) for field in fields(cls))))
|
|
262
|
+
|
|
263
|
+
|
|
264
|
+
class Engine:
|
|
265
|
+
@contextmanager
|
|
266
|
+
def session(self, program: ir.Program, knowledge: tuple[Property, ...] = ()) -> Generator[Arena]:
|
|
267
|
+
assert _active.get(None) is None, "An analysis arena is already active"
|
|
268
|
+
# Importing registers analysis functions; inference remains in rules/.
|
|
269
|
+
from sqlassert.rules import domain, equality, exactly_one, foreign_key, join_cardinality, nullability, uniqueness # noqa: F401
|
|
270
|
+
|
|
271
|
+
arena = Arena(program, knowledge)
|
|
272
|
+
token = _active.set(arena)
|
|
273
|
+
try:
|
|
274
|
+
yield arena
|
|
275
|
+
finally:
|
|
276
|
+
_active.reset(token)
|
|
277
|
+
|
|
278
|
+
def run(
|
|
279
|
+
self, program: ir.Program, knowledge: tuple[Property, ...] = (), diagnostics: tuple[Diagnostic, ...] = (),
|
|
280
|
+
warnings: tuple[Diagnostic, ...] = (),
|
|
281
|
+
) -> Report:
|
|
282
|
+
from sqlassert.rules.uniqueness import minimal_keys
|
|
283
|
+
|
|
284
|
+
with self.session(program, knowledge) as arena:
|
|
285
|
+
assertions = []
|
|
286
|
+
for index, assertion in enumerate(program.assertions, 1):
|
|
287
|
+
evidence = arena.prove(assertion.property)
|
|
288
|
+
if any(diagnostic.code == DUPLICATE_DECLARATION for diagnostic in diagnostics):
|
|
289
|
+
evidence = evidence & unknown("Duplicate declarations prevent accepting a proof", assertion)
|
|
290
|
+
assertions.append(AssertionReport(
|
|
291
|
+
f"assert_{index}", Outcome.PROVED if evidence.value else Outcome.UNKNOWN, assertion.origin,
|
|
292
|
+
ASSERTED_KINDS[type(assertion.property)], evidence,
|
|
293
|
+
))
|
|
294
|
+
facts = {}
|
|
295
|
+
for relation in program.named_relations:
|
|
296
|
+
facts[relation.report_name.lower()] = tuple(
|
|
297
|
+
tuple(column.name for column in key) for key in minimal_keys(relation)
|
|
298
|
+
)
|
|
299
|
+
return Report(tuple(assertions), tuple(diagnostics), RelationFacts(facts), tuple(warnings))
|
sqlassert/reporting.py
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
"""The durable Report an analysis returns: assertion outcomes, diagnostics, and relation facts.
|
|
2
|
+
|
|
3
|
+
The Report holds plain values only, plus each assertion's evidence. It never prints.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
from collections.abc import Sequence
|
|
9
|
+
from dataclasses import dataclass, field
|
|
10
|
+
from enum import Enum
|
|
11
|
+
from typing import TYPE_CHECKING
|
|
12
|
+
|
|
13
|
+
from sqlassert import properties as props
|
|
14
|
+
from sqlassert.diagnostics import Diagnostic
|
|
15
|
+
from sqlassert.provenance import Origin
|
|
16
|
+
|
|
17
|
+
if TYPE_CHECKING:
|
|
18
|
+
from sqlassert.python_engine import Result
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class Outcome(Enum):
|
|
22
|
+
"""PROVED or UNKNOWN. UNKNOWN fails an assertion but is not a Disproof."""
|
|
23
|
+
|
|
24
|
+
PROVED = "proved"
|
|
25
|
+
UNKNOWN = "unknown"
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclass(frozen=True)
|
|
29
|
+
class AssertionReport:
|
|
30
|
+
"""One assertion's outcome. `kind` is the marker that states it
|
|
31
|
+
(`ASSERTED_KINDS`), so a failure names what was not proved."""
|
|
32
|
+
|
|
33
|
+
assertion_id: str
|
|
34
|
+
outcome: Outcome
|
|
35
|
+
origin: Origin
|
|
36
|
+
kind: str
|
|
37
|
+
evidence: Result[bool] | None = field(default=None, compare=False)
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
# The marker each assertable Property is written as, in the words of its `/**ASSERT ...**/`.
|
|
41
|
+
ASSERTED_KINDS: dict[type[props.Property], str] = {
|
|
42
|
+
props.NonNullColumns: "not-null",
|
|
43
|
+
props.NonNullElements: "not-null-elements",
|
|
44
|
+
props.UniqueSet: "unique",
|
|
45
|
+
props.NonNullUniqueSet: "not-null-unique", # also written PRIMARY KEY
|
|
46
|
+
props.FunctionalDependency: "determines",
|
|
47
|
+
props.EnumeratedDomain: "enum",
|
|
48
|
+
props.ReferentialCoverage: "foreign-key",
|
|
49
|
+
props.ForeignKey: "foreign-key",
|
|
50
|
+
props.ExhaustiveCase: "exhaustive",
|
|
51
|
+
props.UniqueJoin: "unique-join",
|
|
52
|
+
props.ManyToOneJoin: "many-to-one-join",
|
|
53
|
+
props.OneToManyJoin: "one-to-many-join",
|
|
54
|
+
props.OneToOneJoin: "one-to-one-join",
|
|
55
|
+
props.ExactlyOneJoin: "exactly-one-join",
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
@dataclass(frozen=True)
|
|
60
|
+
class RelationFacts:
|
|
61
|
+
"""What was proved about every Named Relation in one analysis.
|
|
62
|
+
|
|
63
|
+
Tables and views use their declared name; CTEs use a ``CTE_``-prefixed
|
|
64
|
+
report label. Anonymous Relation Expressions are omitted: ask about the
|
|
65
|
+
assertion they feed into instead.
|
|
66
|
+
|
|
67
|
+
Holds only Unique Sets for now; further properties join it as typed
|
|
68
|
+
methods, the same way, rather than as a generic ask-anything query.
|
|
69
|
+
"""
|
|
70
|
+
|
|
71
|
+
_unique_sets: dict[str, tuple[tuple[str, ...], ...]] = field(default_factory=dict)
|
|
72
|
+
|
|
73
|
+
def unique_sets(self, relation: str) -> tuple[tuple[str, ...], ...]:
|
|
74
|
+
"""The minimal Unique Sets proved for `relation`, smallest first.
|
|
75
|
+
|
|
76
|
+
Every minimal set of up to three columns; when none is that small,
|
|
77
|
+
one minimal set. A superset of any of them is unique too."""
|
|
78
|
+
return self._unique_sets.get(relation.lower(), ())
|
|
79
|
+
|
|
80
|
+
def is_unique(self, relation: str, columns: Sequence[str]) -> bool:
|
|
81
|
+
"""Whether `columns` is guaranteed unique on `relation`: some proved
|
|
82
|
+
Unique Set's members are all among `columns`."""
|
|
83
|
+
candidate = {column.lower() for column in columns}
|
|
84
|
+
return any(set(unique_set) <= candidate for unique_set in self.unique_sets(relation))
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
@dataclass(frozen=True)
|
|
88
|
+
class Report:
|
|
89
|
+
assertions: tuple[AssertionReport, ...] = ()
|
|
90
|
+
diagnostics: tuple[Diagnostic, ...] = ()
|
|
91
|
+
facts: RelationFacts = field(default_factory=RelationFacts)
|
|
92
|
+
warnings: tuple[Diagnostic, ...] = ()
|
|
93
|
+
|
|
94
|
+
@property
|
|
95
|
+
def proved(self) -> bool:
|
|
96
|
+
"""Every assertion proved, and nothing about the program was unsupported.
|
|
97
|
+
|
|
98
|
+
Warnings do not count: they explain UNKNOWN outcomes, never cause them."""
|
|
99
|
+
return not self.diagnostics and all(
|
|
100
|
+
assertion.outcome is Outcome.PROVED for assertion in self.assertions
|
|
101
|
+
)
|
|
102
|
+
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Rule Style Guide
|
|
2
|
+
|
|
3
|
+
Rules are analysis functions. Each returns `Result[Value]`: `.value`
|
|
4
|
+
is the computed Value and the remaining fields directly represent its evidence.
|
|
5
|
+
`@analysis(stratum)` provides declaration lookup and analysis-scoped caching for public and
|
|
6
|
+
internal analysis functions. Its `Stratum` orders facts about one relation: an analysis may
|
|
7
|
+
use facts about the same relation only at its own or a lower stratum, which keeps the
|
|
8
|
+
call graph acyclic; the decorator asserts this on every call. Every concrete public `Property` class has one
|
|
9
|
+
snake-case public analysis function whose parameters match its fields. Internal
|
|
10
|
+
analysis functions start with `_`. `ColumnSet`, `Closure`, and `RowIdentity` are
|
|
11
|
+
ordinary derived values defined in these rules. Uniqueness is a closure question:
|
|
12
|
+
derive dependencies a relation introduces in `_functional_dependencies`, and let
|
|
13
|
+
`_closure` reach into inputs; never copy an input's facts up to its consumer.
|
|
14
|
+
Use explicit matches for semantic dispatch, and fail on unhandled node types. Keep IR traversal and set operations in small helpers so analysis
|
|
15
|
+
functions state their semantic rule directly. Use `&` / `|` or `all_of` /
|
|
16
|
+
`any_of` to preserve evidence; Python's `and` / `or` deliberately reject
|
|
17
|
+
`Result` values. Use `.value` for every result, including Boolean results
|
|
18
|
+
(false means unproved). `&` / `|` and `all_of` / `any_of` compose only
|
|
19
|
+
`Result[bool]` values and retain their evidence.
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
"""Python analysis functions establish public relational properties.
|
|
2
|
+
|
|
3
|
+
Equality groups say which columns carry one value (equality), for facts
|
|
4
|
+
about values.
|
|
5
|
+
|
|
6
|
+
Null sources say why a column may be NULL (nullability). Functional
|
|
7
|
+
dependencies and their closure decide uniqueness: a column set is a Unique
|
|
8
|
+
Set when its closure reaches the relation's Row Identity, and a join is
|
|
9
|
+
many to one when the right columns ON binds reach the right input's
|
|
10
|
+
(uniqueness, join_cardinality). Foreign Keys and Exactly One Joins build on both.
|
|
11
|
+
"""
|