You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 804864d
Browse filesBrowse the repository at this point in the historyBrowse files
$(if$(wildcard$(SYNTAX_ROOT)),$(GATE_DIR)/syntax-coverage missing --root $(SYNTAX_ROOT),@echo "pending: $(DIALECT) has no syntax suite yet")
279
+
$(if$(filter snowflake,$(DIALECT)),cargo run --profile $(VERIFY_PROFILE) --locked -p sqlquack -- pending --cases $(CONVERT_CASES),@echo "pending: $(DIALECT) has no translation suite; Snowflake is the only source dialect today")
280
+
281
+
check-syntax: ## Rerun DIALECT's parser against its recorded syntax evidence, offline.
282
+
$(suite_dialect)
283
+
@test -d $(SYNTAX_ROOT)|| { echo"check-syntax: $(DIALECT) has no recorded syntax evidence yet">&2;exit 2; }
# together; any failure fails the gate. The fuzz smoke and then the SQL timing benchmark run alone
419
+
# afterwards, so each gets the machine to itself.
420
+
gate: check-ci $(if$(filter command line,$(origin DUCKSHOP_COMPILED)),,duckshop-compiled)## Everything: check-ci, the tests, the replay, DuckShop, fuzz and the SQL benchmark.
make check-syntax DIALECT=snowflake # rerun the parser against recorded syntax evidence
70
+
make check-convert DIALECT=snowflake # replay recorded translations on DuckDB
71
+
```
72
+
73
+
| Command | What it does |
74
+
|---|---|
75
+
|`make pending DIALECT=snowflake`| What isn't recorded yet, in both suites |
76
+
|`make check-syntax DIALECT=snowflake`| Rerun the parser against recorded evidence (offline) |
77
+
|`make record-syntax DIALECT=duckdb`| Record evidence for new syntax cases |
78
+
|`make check-convert DIALECT=snowflake [CASES=cases/temporal]`| Replay recorded translations on DuckDB (offline) |
79
+
|`make record-convert DIALECT=snowflake`| Record new translation cases on Snowflake |
80
+
81
+
Recording needs the dialect's engine: DuckDB and SQLite record locally, while Snowflake, BigQuery and Databricks need a connection. Recording Snowflake syntax evidence isn't public yet. `make help` lists every target.
82
+
62
83
---
63
84
64
85
Built in Rust. Free and open source. [Apache 2.0](https://github.com/sqlstack-io/sqlquack/blob/main/LICENSE).
Copy file name to clipboardExpand all lines: docs/architecture.md
+28-6Lines changed: 28 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -442,6 +442,22 @@ Recorded warehouse results are the only arbiter of correctness. Recording runs o
442
442
the maintainer; results are append-only and named by the hash of their case, and everything that
443
443
could be weakened to make a failing case pass lives in one reviewed policy file.
444
444
445
+
### Running the suites
446
+
447
+
Each suite has one pattern for every dialect, and `make help` lists the targets. The check- targets
448
+
replay committed evidence offline; the record- targets need the dialect's engine or account and
449
+
refuse when `RECORDER=0`. Every target needs `DIALECT`; no dialect is the default.
450
+
451
+
| Target | What it does |
452
+
|---|---|
453
+
|`make pending DIALECT=<d>`| Lists what is not recorded yet: the syntax suite's unmet obligations (`syntax-coverage missing`) and, for Snowflake, writes the translation suite's pending cases. |
454
+
|`make check-syntax DIALECT=<d>`| Reparses every recorded syntax case of `coverage/syntax-<d>` (`coverage/syntax` for Snowflake) and compares with its receipts: `syntax-coverage diff` against the baseline where there is one, `summary` otherwise. `make check-ci` runs it for Snowflake, SQLite and DuckDB. |
455
+
|`make record-syntax DIALECT=<d>`| Runs the dialect's syntax referee, `scripts/run_<d>_receipts.py run`, with its arguments in `RECORD_ARGS`. Snowflake's capture tool and the Postgres referee are not in the repository yet, so it refuses those. |
456
+
|`make check-convert DIALECT=snowflake [CASES=<folder>]`| Replays recorded translations on DuckDB (`make verify-recorded`, or only `CASES`). |
457
+
|`make record-convert DIALECT=snowflake`| Writes the pending cases and records them on Snowflake (Flow, below). |
458
+
459
+
Every conversion targets DuckDB, so only the source dialect is named; Snowflake is the only one today.
460
+
445
461
### Cases
446
462
447
463
Case files live under `cases/<category>/<construct>.toml`. Each file names an edge-case category
@@ -607,8 +623,11 @@ setting reaches the repository. A pinned parameter whose account default differs
607
623
608
624
### Flow
609
625
610
-
1.`sqlquack pending` writes `evidence/pending/<hash>.json` for every case without a result.
611
-
2. The maintainer runs `sqlquack-record`. Before running anything it compiles every pending
626
+
1.`make pending DIALECT=snowflake` (`sqlquack pending`) writes `evidence/pending/<hash>.json` for
627
+
every case without a result.
628
+
2. The maintainer runs `make record-convert DIALECT=snowflake` (`sqlquack pending`, then
629
+
`sqlquack-record` with any options in `RECORD_ARGS`) from a machine with a Snowflake connection;
630
+
CI never records, and the target refuses when `RECORDER=0`. Before running anything it compiles every pending
612
631
case's SQL with `EXPLAIN`, which runs nothing and creates nothing, and when any fails with a
613
632
SQLSTATE class 0A or 42 error it stops and lists them, so a mistake such as a reserved word used
614
633
as an alias costs no recording. A case that records Snowflake refusing to compile its SQL
@@ -637,8 +656,12 @@ setting reaches the repository. A pinned parameter whose account default differs
637
656
(the outermost `input` CTE and an `ORDER BY ordinal` that only keeps rows in input order) is
638
657
converted with provenance muted, so its casts, literals and set operation count neither toward
639
658
claims nor toward the error check's declared failures; a query's own CTEs follow the fixture's
640
-
in the same `WITH` and do count. The pre-push gate
641
-
(`make gate`) runs `verify --require-verified`, which fails while any claim is unverified.
659
+
in the same `WITH` and do count. `make check-convert DIALECT=snowflake` runs `make
660
+
verify-recorded`, which runs `verify --require-verified --strict-errors` and fails while any
661
+
claim is unverified; CI and `make gate` both run it, so both use those flags. `CASES=<folder>`
662
+
replays only that folder, with `--strict-errors` alone. `make check-merge` does not replay
663
+
recorded cases. A new case's results are committed with the case once `make check-convert
664
+
DIALECT=snowflake` passes.
642
665
Where Snowflake and DuckDB both raised, verify also checks the errors (see Error checks).
643
666
4.`sqlquack review` writes every case as a sqllogictest-style record (`source snowflake`,
644
667
`converted duckdb` or `refused`, then `query snowflake nosort|rowsort` with the column names and
@@ -711,5 +734,4 @@ For a passed case where both raised, verify reports `agrees` (same kind, and a r
711
734
conversion used declares the recorded error), `divergence_raise` (DuckDB raised a known
712
735
divergence's guard), or a finding: `errno_mismatch` (a block tagged another errno),
713
736
`kind_mismatch`, `undeclared` or `unknown_snowflake_error`. Findings are reported and counted;
714
-
`verify --strict-errors` fails on them. The gate does not pass that flag until the existing
715
-
error cases are re-recorded with their messages.
737
+
`verify --strict-errors` fails on them; `make verify-recorded`, and so CI and `make gate`, pass it.
0 commit comments