chqce 0.1.0__tar.gz

chqce-0.1.0/LICENSE

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

chqce-0.1.0/PKG-INFO

@@ -0,0 +1,223 @@
+Metadata-Version: 2.4
+Name: chqce
+Version: 0.1.0
+Summary: ClickHouse Query Cost Estimator CLI
+Author-email: Ahmad Darwich <darw.ahmad@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/AhmadDarwich/clickhouse-query-cost-estimator
+Project-URL: Repository, https://github.com/AhmadDarwich/clickhouse-query-cost-estimator
+Project-URL: Issues, https://github.com/AhmadDarwich/clickhouse-query-cost-estimator/issues
+Keywords: clickhouse,sql,cli,query,cost,performance,explain
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: clickhouse-connect>=0.7.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: click>=8.1.0
+Requires-Dist: sqlglot>=20.0.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Dynamic: license-file
+
+# clickhouse-query-cost-estimator
+
+[![CI](https://github.com/AhmadDarwich/clickhouse-query-cost-estimator/actions/workflows/ci.yml/badge.svg)](https://github.com/AhmadDarwich/clickhouse-query-cost-estimator/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/chqce.svg)](https://pypi.org/project/chqce/)
+[![Python versions](https://img.shields.io/pypi/pyversions/chqce.svg)](https://pypi.org/project/chqce/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A terminal CLI that estimates the cost of a ClickHouse SQL query **before you regret running it**, and helps you tune indexes afterwards.
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│ ClickHouse Query Cost Estimator  v0.1.0                      │
+│ Connected to localhost:8123  ·  database: default  ·  23.8  │
+╰──────────────────────────────────────────────────────────────╯
+
+Cost Estimate  (from EXPLAIN ESTIMATE)
+ Database  Table   Parts  Est. Rows  Marks
+ default   orders     12    4.5M     550
+
+Timing
+ Phase                       Time        Notes
+ SQL Analyzer (EXPLAIN)      2.1 ms      parsing + plan generation
+ Execution (client)        234.5 ms      wall-clock including network
+ Execution (server)        228.3 ms      server-side only
+
+Execution Stats
+ Rows read      4.5M      Bytes read   1.2 GB
+ Result rows    18.2K     Peak memory  45.6 MB
+
+── Index Suggestions ──────────────────────────────────────────
+  ✓  created_at  —  already in ORDER BY
+  ⚠  user_id    —  not in ORDER BY
+     ALTER TABLE default.orders
+         ADD INDEX idx_orders_user_id user_id
+         TYPE bloom_filter(0.01) GRANULARITY 4;
+```
+
+## What it tells you
+
+| Metric | Source |
+|---|---|
+| **Estimated rows / parts / marks** | `EXPLAIN ESTIMATE` |
+| **SQL analyzer time** | time to run `EXPLAIN PLAN` (parsing + planning) |
+| **Execution time (client)** | wall-clock including network round-trip |
+| **Execution time (server)** | `elapsed_ns` from `X-ClickHouse-Summary` header |
+| **Rows / bytes read, peak memory** | `system.query_log` after execution |
+| **Index suggestions** | `system.tables` ORDER BY vs WHERE columns |
+
+## Installation
+
+```bash
+pip install chqce
+```
+
+Or, for local development:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Analyze a single query
+chqce "SELECT count() FROM hits WHERE EventDate = today()"
+
+# Interactive mode — paste any query, then type ; or GO to submit
+chqce
+
+# Custom connection
+chqce --host my.ch.host --port 9123 --user admin --database analytics \
+      "SELECT count() FROM events WHERE user_id = 42"
+
+# Estimate only — skip execution (safe for expensive/destructive queries)
+chqce --no-execute "SELECT * FROM huge_table WHERE x > 0"
+```
+
+### Large queries
+
+For big, multi-line queries (hundreds or thousands of lines) you don't want to
+wrestle with shell quoting. Read the query from a file or pipe it in instead:
+
+```bash
+# From a file — the cleanest option for huge queries
+chqce -f report.sql
+
+# Piped via stdin
+cat report.sql | chqce
+chqce < report.sql
+
+# If ClickHouse rejects it with a max_query_size error, raise the limit
+chqce -f report.sql --max-query-size 1048576   # 1 MiB
+```
+
+The query source is resolved in this priority order:
+
+1. `--file` / `-f` — read from a file
+2. `QUERY` argument — passed on the command line
+3. piped **stdin** — when input isn't a terminal
+4. interactive prompt — when nothing else is provided
+
+The echoed query is truncated to the first 30 lines in the output, so a large
+query never buries the results.
+
+### Timeouts and resource limits
+
+Heavy queries can hit server-side limits. The tool catches these, reports them
+clearly, and tells you which flag gets you unstuck:
+
+```bash
+# Abort the query after 5 minutes instead of waiting indefinitely
+chqce -t 300 "SELECT ... a slow aggregation ..."
+
+# Fix "AST is too big" (e.g. a giant IN (...) list)
+chqce -f report.sql --max-ast-elements 500000
+
+# Fix "Max query size exceeded"
+chqce -f report.sql --max-query-size 1048576   # 1 MiB
+```
+
+When a query fails, the error is classified and shown with suggestions. For
+example, a timeout renders as:
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│ ✗  Execution error  Query timed out                          │
+│ Code: 159. DB::Exception: Timeout exceeded: elapsed 30 ...   │
+│                                                              │
+│ Suggestions                                                  │
+│ The query exceeded its time budget. Try:                     │
+│   • raise the limit:  --timeout 600  (seconds, 0 = unlimited)│
+│   • estimate without running:  --no-execute                  │
+│   • narrow the query with a WHERE filter or LIMIT            │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+Recognized failures: **timeout**, **AST too big**, **parser depth**,
+**query size**, **memory limit**, and **read-row/byte limits**.
+
+## Options
+
+| Flag | Env var | Default | Description |
+|---|---|---|---|
+| `--file` / `-f` | — | — | Read the query from a file (best for huge queries) |
+| `--host` / `-H` | `CLICKHOUSE_HOST` | `localhost` | ClickHouse host |
+| `--port` / `-p` | `CLICKHOUSE_PORT` | `8123` | HTTP port |
+| `--user` / `-u` | `CLICKHOUSE_USER` | `default` | Username |
+| `--password` / `-P` | `CLICKHOUSE_PASSWORD` | _(empty)_ | Password |
+| `--database` / `-d` | `CLICKHOUSE_DATABASE` | `default` | Default database |
+| `--timeout` / `-t` | — | `0` _(unlimited)_ | Server-side `max_execution_time` in seconds |
+| `--max-query-size` | — | _(server default 262144)_ | Raise ClickHouse `max_query_size` for very large queries |
+| `--max-ast-elements` | — | _(server default 50000)_ | Raise ClickHouse `max_ast_elements` for queries with huge ASTs |
+| `--no-execute` | — | `false` | Skip actual execution; estimate only |
+
+## Interactive mode
+
+Type or paste a multi-line query, then submit by:
+- Ending the last line with `;`
+- Typing `GO` on its own line
+
+Press **Ctrl+C** to exit.
+
+## How index suggestions work
+
+1. The query is parsed with [sqlglot](https://github.com/tobymao/sqlglot) to extract WHERE-clause columns and condition types (equality, range, LIKE, IN).
+2. Each referenced table's `sorting_key` is fetched from `system.tables`.
+3. Columns not covered by the sort key get a skip-index `ALTER TABLE` suggestion, with the type chosen by condition and column type:
+
+| Condition | Column type | Suggested index |
+|---|---|---|
+| `LIKE` / `ILIKE` | any | `tokenbf_v1(32768, 3, 0)` |
+| `>` / `<` / `BETWEEN` | any | `minmax` |
+| `=` / `IN` | String | `bloom_filter(0.01)` |
+| `=` / `IN` | numeric / date | `set(100)` |
+
+## Requirements
+
+- Python ≥ 3.10
+- ClickHouse with HTTP interface enabled (default port 8123)
+
+## Development
+
+Run the test suite (no ClickHouse server required — tests use a fake client):
+
+```bash
+pip install -e ".[test]"   # or: pip install -r requirements-dev.txt
+pytest
+```
+
+The tests live in `tests/` and cover error classification, the estimator,
+index suggestions, output formatting, connection settings, and the CLI.

chqce-0.1.0/README.md

@@ -0,0 +1,191 @@
+# clickhouse-query-cost-estimator
+
+[![CI](https://github.com/AhmadDarwich/clickhouse-query-cost-estimator/actions/workflows/ci.yml/badge.svg)](https://github.com/AhmadDarwich/clickhouse-query-cost-estimator/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/chqce.svg)](https://pypi.org/project/chqce/)
+[![Python versions](https://img.shields.io/pypi/pyversions/chqce.svg)](https://pypi.org/project/chqce/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+A terminal CLI that estimates the cost of a ClickHouse SQL query **before you regret running it**, and helps you tune indexes afterwards.
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│ ClickHouse Query Cost Estimator  v0.1.0                      │
+│ Connected to localhost:8123  ·  database: default  ·  23.8  │
+╰──────────────────────────────────────────────────────────────╯
+
+Cost Estimate  (from EXPLAIN ESTIMATE)
+ Database  Table   Parts  Est. Rows  Marks
+ default   orders     12    4.5M     550
+
+Timing
+ Phase                       Time        Notes
+ SQL Analyzer (EXPLAIN)      2.1 ms      parsing + plan generation
+ Execution (client)        234.5 ms      wall-clock including network
+ Execution (server)        228.3 ms      server-side only
+
+Execution Stats
+ Rows read      4.5M      Bytes read   1.2 GB
+ Result rows    18.2K     Peak memory  45.6 MB
+
+── Index Suggestions ──────────────────────────────────────────
+  ✓  created_at  —  already in ORDER BY
+  ⚠  user_id    —  not in ORDER BY
+     ALTER TABLE default.orders
+         ADD INDEX idx_orders_user_id user_id
+         TYPE bloom_filter(0.01) GRANULARITY 4;
+```
+
+## What it tells you
+
+| Metric | Source |
+|---|---|
+| **Estimated rows / parts / marks** | `EXPLAIN ESTIMATE` |
+| **SQL analyzer time** | time to run `EXPLAIN PLAN` (parsing + planning) |
+| **Execution time (client)** | wall-clock including network round-trip |
+| **Execution time (server)** | `elapsed_ns` from `X-ClickHouse-Summary` header |
+| **Rows / bytes read, peak memory** | `system.query_log` after execution |
+| **Index suggestions** | `system.tables` ORDER BY vs WHERE columns |
+
+## Installation
+
+```bash
+pip install chqce
+```
+
+Or, for local development:
+
+```bash
+pip install -e .
+```
+
+## Usage
+
+```bash
+# Analyze a single query
+chqce "SELECT count() FROM hits WHERE EventDate = today()"
+
+# Interactive mode — paste any query, then type ; or GO to submit
+chqce
+
+# Custom connection
+chqce --host my.ch.host --port 9123 --user admin --database analytics \
+      "SELECT count() FROM events WHERE user_id = 42"
+
+# Estimate only — skip execution (safe for expensive/destructive queries)
+chqce --no-execute "SELECT * FROM huge_table WHERE x > 0"
+```
+
+### Large queries
+
+For big, multi-line queries (hundreds or thousands of lines) you don't want to
+wrestle with shell quoting. Read the query from a file or pipe it in instead:
+
+```bash
+# From a file — the cleanest option for huge queries
+chqce -f report.sql
+
+# Piped via stdin
+cat report.sql | chqce
+chqce < report.sql
+
+# If ClickHouse rejects it with a max_query_size error, raise the limit
+chqce -f report.sql --max-query-size 1048576   # 1 MiB
+```
+
+The query source is resolved in this priority order:
+
+1. `--file` / `-f` — read from a file
+2. `QUERY` argument — passed on the command line
+3. piped **stdin** — when input isn't a terminal
+4. interactive prompt — when nothing else is provided
+
+The echoed query is truncated to the first 30 lines in the output, so a large
+query never buries the results.
+
+### Timeouts and resource limits
+
+Heavy queries can hit server-side limits. The tool catches these, reports them
+clearly, and tells you which flag gets you unstuck:
+
+```bash
+# Abort the query after 5 minutes instead of waiting indefinitely
+chqce -t 300 "SELECT ... a slow aggregation ..."
+
+# Fix "AST is too big" (e.g. a giant IN (...) list)
+chqce -f report.sql --max-ast-elements 500000
+
+# Fix "Max query size exceeded"
+chqce -f report.sql --max-query-size 1048576   # 1 MiB
+```
+
+When a query fails, the error is classified and shown with suggestions. For
+example, a timeout renders as:
+
+```
+╭──────────────────────────────────────────────────────────────╮
+│ ✗  Execution error  Query timed out                          │
+│ Code: 159. DB::Exception: Timeout exceeded: elapsed 30 ...   │
+│                                                              │
+│ Suggestions                                                  │
+│ The query exceeded its time budget. Try:                     │
+│   • raise the limit:  --timeout 600  (seconds, 0 = unlimited)│
+│   • estimate without running:  --no-execute                  │
+│   • narrow the query with a WHERE filter or LIMIT            │
+╰──────────────────────────────────────────────────────────────╯
+```
+
+Recognized failures: **timeout**, **AST too big**, **parser depth**,
+**query size**, **memory limit**, and **read-row/byte limits**.
+
+## Options
+
+| Flag | Env var | Default | Description |
+|---|---|---|---|
+| `--file` / `-f` | — | — | Read the query from a file (best for huge queries) |
+| `--host` / `-H` | `CLICKHOUSE_HOST` | `localhost` | ClickHouse host |
+| `--port` / `-p` | `CLICKHOUSE_PORT` | `8123` | HTTP port |
+| `--user` / `-u` | `CLICKHOUSE_USER` | `default` | Username |
+| `--password` / `-P` | `CLICKHOUSE_PASSWORD` | _(empty)_ | Password |
+| `--database` / `-d` | `CLICKHOUSE_DATABASE` | `default` | Default database |
+| `--timeout` / `-t` | — | `0` _(unlimited)_ | Server-side `max_execution_time` in seconds |
+| `--max-query-size` | — | _(server default 262144)_ | Raise ClickHouse `max_query_size` for very large queries |
+| `--max-ast-elements` | — | _(server default 50000)_ | Raise ClickHouse `max_ast_elements` for queries with huge ASTs |
+| `--no-execute` | — | `false` | Skip actual execution; estimate only |
+
+## Interactive mode
+
+Type or paste a multi-line query, then submit by:
+- Ending the last line with `;`
+- Typing `GO` on its own line
+
+Press **Ctrl+C** to exit.
+
+## How index suggestions work
+
+1. The query is parsed with [sqlglot](https://github.com/tobymao/sqlglot) to extract WHERE-clause columns and condition types (equality, range, LIKE, IN).
+2. Each referenced table's `sorting_key` is fetched from `system.tables`.
+3. Columns not covered by the sort key get a skip-index `ALTER TABLE` suggestion, with the type chosen by condition and column type:
+
+| Condition | Column type | Suggested index |
+|---|---|---|
+| `LIKE` / `ILIKE` | any | `tokenbf_v1(32768, 3, 0)` |
+| `>` / `<` / `BETWEEN` | any | `minmax` |
+| `=` / `IN` | String | `bloom_filter(0.01)` |
+| `=` / `IN` | numeric / date | `set(100)` |
+
+## Requirements
+
+- Python ≥ 3.10
+- ClickHouse with HTTP interface enabled (default port 8123)
+
+## Development
+
+Run the test suite (no ClickHouse server required — tests use a fake client):
+
+```bash
+pip install -e ".[test]"   # or: pip install -r requirements-dev.txt
+pytest
+```
+
+The tests live in `tests/` and cover error classification, the estimator,
+index suggestions, output formatting, connection settings, and the CLI.

chqce-0.1.0/chqce/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

chqce-0.1.0/chqce/cli.py

@@ -0,0 +1,163 @@
+import sys
+
+import click
+from rich.console import Console
+
+from . import __version__
+from .connection import create_client, test_connection
+from .estimator import QueryEstimator
+from .formatter import console, print_header, print_result
+from .suggestions import get_index_suggestions
+
+_err = Console(stderr=True)
+
+
+def _collect_interactive() -> str:
+    """Collect a multi-line SQL query from stdin.
+
+    Submit by ending a line with ';' or typing GO on its own line.
+    """
+    console.print(
+        "\n[dim]Paste or type your SQL query."
+        "  End with [bold];[/bold] or type [bold]GO[/bold] on its own line."
+        "  [bold]Ctrl+C[/bold] to exit.[/dim]\n"
+    )
+    lines: list[str] = []
+    try:
+        while True:
+            prefix = "[bold cyan]SQL>[/bold cyan] " if not lines else "     [dim]>[/dim] "
+            console.print(prefix, end="")
+            try:
+                line = input()
+            except EOFError:
+                break
+            stripped = line.strip()
+            if stripped.upper() == "GO" or stripped == ";":
+                if lines:
+                    break
+                continue
+            lines.append(line)
+            if stripped.endswith(";"):
+                break
+    except KeyboardInterrupt:
+        console.print("\n[dim]Bye![/dim]")
+        sys.exit(0)
+
+    return "\n".join(lines).strip()
+
+
+def _resolve_query(query: str | None, file: str | None) -> str | None:
+    """Determine the query source, in priority order.
+
+    1. --file FILE          read the query from a file (best for huge queries)
+    2. QUERY argument       passed directly on the command line
+    3. piped stdin          e.g.  `chqce < query.sql`  or  `cat q.sql | chqce`
+    4. None                 -> caller falls back to interactive mode
+    """
+    if file:
+        with open(file, "r", encoding="utf-8") as fh:
+            return fh.read().strip()
+    if query:
+        return query
+    # Query piped in on stdin (non-interactive).
+    if not sys.stdin.isatty():
+        data = sys.stdin.read().strip()
+        if data:
+            return data
+    return None
+
+
+def _run(query: str, estimator: QueryEstimator, client, database: str, execute: bool) -> None:
+    with console.status("[bold green]Analyzing…[/bold green]", spinner="dots"):
+        result = estimator.estimate(query, execute=execute)
+        suggestions = get_index_suggestions(query, client, current_database=database)
+    print_result(result, suggestions)
+
+
+@click.command(context_settings={"help_option_names": ["-h", "--help"]})
+@click.argument("query", required=False)
+@click.option("--file", "-f", "file", type=click.Path(exists=True, dir_okay=False),
+              default=None, help="Read the query from a file (best for huge queries)")
+@click.option("--host", "-H", default="localhost", envvar="CLICKHOUSE_HOST",
+              show_default=True, help="ClickHouse host")
+@click.option("--port", "-p", default=8123, envvar="CLICKHOUSE_PORT", type=int,
+              show_default=True, help="HTTP(S) port")
+@click.option("--user", "-u", default="default", envvar="CLICKHOUSE_USER",
+              show_default=True, help="Username")
+@click.option("--password", "-P", default="", envvar="CLICKHOUSE_PASSWORD",
+              help="Password (or set CLICKHOUSE_PASSWORD)")
+@click.option("--database", "-d", default="default", envvar="CLICKHOUSE_DATABASE",
+              show_default=True, help="Default database")
+@click.option("--max-query-size", default=0, type=int, metavar="BYTES",
+              help="Raise ClickHouse max_query_size for very large queries "
+                   "(server default is 262144)")
+@click.option("--timeout", "-t", default=0, type=int, metavar="SECONDS",
+              help="Server-side max_execution_time; query is aborted after this "
+                   "many seconds (0 = unlimited)")
+@click.option("--max-ast-elements", default=0, type=int, metavar="N",
+              help="Raise ClickHouse max_ast_elements for queries that fail with "
+                   "'AST is too big' (server default is 50000)")
+@click.option("--no-execute", is_flag=True, default=False,
+              help="Estimate only — do not actually run the query")
+@click.version_option(__version__, "-V", "--version")
+def cli(query, file, host, port, user, password, database, max_query_size,
+        timeout, max_ast_elements, no_execute):
+    """ClickHouse Query Cost Estimator.
+
+    Estimates rows scanned, memory usage, and execution time for a ClickHouse
+    SQL query, and suggests indexes based on WHERE-clause columns.
+
+    \b
+    The query can come from (in priority order):
+      • --file query.sql      best for huge / multi-line queries
+      • a QUERY argument       chqce "SELECT ..."
+      • piped stdin            chqce < query.sql
+      • interactive prompt     run with no query at all
+
+    \b
+    Environment variables (override defaults):
+      CLICKHOUSE_HOST, CLICKHOUSE_PORT, CLICKHOUSE_USER,
+      CLICKHOUSE_PASSWORD, CLICKHOUSE_DATABASE
+
+    \b
+    Examples:
+      chqce "SELECT count() FROM hits WHERE EventDate = today()"
+      chqce -f report.sql --no-execute
+      chqce -t 600 "SELECT ... a slow query ..."
+      cat report.sql | chqce --max-query-size 1048576 --max-ast-elements 500000
+    """
+    try:
+        resolved = _resolve_query(query, file)
+    except OSError as e:
+        _err.print(f"[red]Could not read query file:[/red] {e}")
+        sys.exit(1)
+
+    try:
+        client = create_client(host=host, port=port, user=user,
+                               password=password, database=database,
+                               max_query_size=max_query_size,
+                               max_execution_time=timeout,
+                               max_ast_elements=max_ast_elements)
+        ok, version_or_err = test_connection(client)
+    except Exception as e:
+        _err.print(f"[red]Connection error:[/red] {e}")
+        sys.exit(1)
+
+    if not ok:
+        _err.print(f"[red]Connection failed:[/red] {version_or_err}")
+        sys.exit(1)
+
+    print_header(version_or_err, host, port, database)
+
+    estimator = QueryEstimator(client)
+    execute = not no_execute
+
+    if resolved:
+        _run(resolved, estimator, client, database, execute)
+    else:
+        while True:
+            q = _collect_interactive()
+            if not q:
+                continue
+            _run(q, estimator, client, database, execute)
+            console.print("[dim]" + "─" * 60 + "[/dim]")

chqce-0.1.0/chqce/connection.py

@@ -0,0 +1,55 @@
+import clickhouse_connect
+from clickhouse_connect.driver import Client
+
+
+DEFAULT_SOCKET_TIMEOUT = 300
+
+
+def create_client(
+    host: str = "localhost",
+    port: int = 8123,
+    user: str = "default",
+    password: str = "",
+    database: str = "default",
+    max_query_size: int = 0,
+    max_execution_time: int = 0,
+    max_ast_elements: int = 0,
+) -> Client:
+    # Per-session ClickHouse settings, only sent when the caller overrides them.
+    settings = {}
+    if max_query_size > 0:
+        # ClickHouse rejects queries larger than max_query_size (256 KiB default).
+        settings["max_query_size"] = max_query_size
+    if max_execution_time > 0:
+        # Server aborts the query after this many seconds (0 = unlimited).
+        settings["max_execution_time"] = max_execution_time
+    if max_ast_elements > 0:
+        # Raises the limit on parsed-query size (huge IN-lists, deep nesting).
+        settings["max_ast_elements"] = max_ast_elements
+        settings["max_expanded_ast_elements"] = max_ast_elements
+
+    # Keep the client socket alive a bit longer than the server-side limit so
+    # ClickHouse returns a clean timeout error instead of the socket dropping.
+    socket_timeout = DEFAULT_SOCKET_TIMEOUT
+    if max_execution_time > 0:
+        socket_timeout = max_execution_time + 30
+
+    return clickhouse_connect.get_client(
+        host=host,
+        port=port,
+        username=user,
+        password=password,
+        database=database,
+        connect_timeout=10,
+        send_receive_timeout=socket_timeout,
+        settings=settings,
+    )
+
+
+def test_connection(client: Client) -> tuple[bool, str]:
+    try:
+        result = client.query("SELECT version()")
+        version = result.result_rows[0][0]
+        return True, version
+    except Exception as e:
+        return False, str(e)