Metadata-Version: 2.4
Name: sqlquack-cli
Version: 0.7.0
License-File: LICENSE
License-File: THIRD_PARTY_NOTICES
Summary: The native sqlquack executable: check Snowflake SQL and convert it into DuckDB SQL.
Home-Page: https://github.com/sqlstack-io/sqlquack
License-Expression: Apache-2.0 AND MIT
Requires-Python: >=3.12
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/sqlstack-io/sqlquack/main/.github/sqlquack-logo-dark.png">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/sqlstack-io/sqlquack/main/.github/sqlquack-logo-light.png">
    <img src="https://raw.githubusercontent.com/sqlstack-io/sqlquack/main/.github/sqlquack-logo-light.png" alt="SQLQuack" width="420">
  </picture>
  <br>
  <sub>by <a href="https://sqlstack.io">SQLStack</a></sub>
</p>

<h3 align="center">Run warehouse SQL locally.</h3>

<p align="center">
  Translate warehouse SQL into DuckDB SQL for local testing and CI - without a running warehouse.
  <br>
  <a href="https://sqlquack.io/">Website</a> ·
  <a href="https://sqlquack.io/docs/">Docs</a> ·
  <a href="https://sqlquack.io/playground/">Playground</a> ·
  <a href="https://sqlquack.io/docs/quickstart/">Quickstart</a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/sqlstack-io/sqlquack/main/.github/demos/check-convert.gif" alt="SQLQuack checks SQL and converts queries to DuckDB SQL">
</p>

## Why SQLQuack?

SQL that runs on two engines doesn't always return the same answer. NULLs, decimal arithmetic and casts can behave differently.

SQLQuack checks its conversion rules against real results from the source warehouse. It handles those differences deliberately and gives you precise diagnostics when it can't convert a query - not plausible-looking SQL and crossed fingers.

SQLQuack's parser started as a fork of [Polyglot](https://github.com/tobilg/polyglot), a Rust SQL transpiler inspired by [SQLGlot](https://github.com/tobymao/sqlglot). The translation to DuckDB, the typing and the recorded evidence behind them are SQLQuack's own.

- **Check early.** Catch invalid SQL before it reaches the warehouse.
- **Test locally.** Convert queries to DuckDB SQL for tests against small fixtures.
- **See what's blocking you.** Scan a SQL project to find what converts and what needs attention.
- **Choose what to accept.** Allow or refuse each known difference in `sqlquack.toml`.

## Get started

```bash
pip install sqlquack

# Convert your first query
echo "SELECT 1 AS total" | sqlquack convert --no-config

# Check a SQL file
sqlquack check query.sql

# Convert a query using the tables in sources/*.yml
sqlquack convert query.sql
```

Or **[try the playground](https://sqlquack.io/playground/)** - no installation needed.

See the [supported dialects and coverage](https://sqlquack.io/docs/coverage/), [project guide](https://sqlquack.io/docs/project/) and [defaults for known differences](https://sqlquack.io/docs/policy/) for the details.

## Use it from Python

```python
import sqlquack

result = sqlquack.convert(
    sql="SELECT 1 AS total",
    options=sqlquack.ConvertOptions(no_config=True),
)
```

[Python API](https://sqlquack.io/docs/python/)

## Running the suites

SQLQuack's parsers and conversion rules are checked against evidence recorded on the real engines. Rerunning it needs no account:

```bash
git clone https://github.com/sqlstack-io/sqlquack && cd sqlquack
uv sync
make check-syntax DIALECT=snowflake    # rerun the parser against recorded syntax evidence
make check-convert DIALECT=snowflake   # replay recorded translations on DuckDB
```

| Command | What it does |
|---|---|
| `make pending DIALECT=snowflake` | What isn't recorded yet, in both suites |
| `make check-syntax DIALECT=snowflake` | Rerun the parser against recorded evidence (offline) |
| `make record-syntax DIALECT=duckdb` | Record evidence for new syntax cases |
| `make check-convert DIALECT=snowflake [CASES=temporal]` | Replay recorded translations on DuckDB (offline) |
| `make record-convert DIALECT=snowflake` | Record new translation cases on Snowflake |
| `make verify-changed` | Replay only the cases whose conversion or recording changed since its last run |
| `make check-merge` | The static checks and the Rust tests every change must pass |
| `make test-crate CRATE=sqlquack-evidence` | One crate's tests |
| `make python-api` | Build the Python module and run its API tests |

A pull request runs what its changed files need. Documentation and website changes build and check the site. Other changes run `make check-merge`, the Python tests and the replay. The replay reuses main's judgement for every case whose conversion and recording are unchanged, and replays only the rest. A change under one of the full-replay paths in `scripts/replay_scope/constants.py` replays every case: the DuckDB pin, the lock files, the replay, comparison and policy crates, the error kinds, CI's toolchain and the evidence pin. A change outside every crate the `sqlquack` binary is built from replays nothing.

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.

## Credits

SQLQuack wouldn't exist without two projects:

- **[Polyglot](https://github.com/tobilg/polyglot)** by Tobias ([@tobilg](https://github.com/tobilg)). SQLQuack's tokenizer, parser and syntax tree are a modified fork of Polyglot's, and much of that code is still his. Tobias also fixed many issues I reported while building SQLBuild on Polyglot.
- **[SQLGlot](https://github.com/tobymao/sqlglot)** by Toby Mao and contributors, for years of work on SQL transpilation that this space builds on.

Both are MIT licensed. Their licence texts are in [THIRD_PARTY_NOTICES](THIRD_PARTY_NOTICES) and ship with every release.

SQLQuack goes a different way from both on translation. It doesn't rewrite the tree and print it out. It checks each rule against recorded warehouse results and refuses what it can't prove.

---

Built in Rust. Free and open source. [Apache 2.0](https://github.com/sqlstack-io/sqlquack/blob/main/LICENSE).

Part of [SQLStack](https://sqlstack.io/).

