queryview 0.0.3__tar.gz → 0.0.4__tar.gz

{queryview-0.0.3 → queryview-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: queryview
-Version: 0.0.3
+Version: 0.0.4
 Summary: QueryView: FastAPI + SQLModel backend and React SPA over the ClickHouse HTTP interface
 Project-URL: Homepage, https://github.com/kolodkin/queryview
 Project-URL: Repository, https://github.com/kolodkin/queryview

{queryview-0.0.3 → queryview-0.0.4}/backend/queryview/connect.py

@@ -422,15 +422,32 @@ async def run_query(
     sql: str,
     limit: int,
     offset: int,
-    fmt: str,
     order_by: list[dict[str, Any]] | None = None,
 ) -> dict[str, Any]:
-    """Run a paginated SQL query against this session's selected database. The
-    driver owns pagination/quoting; `fmt` is the logical 'tsv'/'csv'."""
+    """Run a paginated SQL query against this session's selected database and
+    return `{ok, meta: [{name, type}], data: [[…]]}`. The driver owns
+    pagination/quoting."""
     s, err = await _gated_session(sid)
     if s is None:
         return err  # type: ignore[return-value]
-    r = await DRIVERS[s.type].run_query(s.config, sql, s.database, limit, offset, order_by, fmt)
+    r = await DRIVERS[s.type].run_query(s.config, sql, s.database, limit, offset, order_by)
+    if not r.ok or r.rows is None:
+        return {"ok": False, "message": r.message}
+    return {"ok": True, "meta": [c._asdict() for c in r.rows.meta], "data": r.rows.data}
+
+
+async def export_csv(
+    sid: str,
+    sql: str,
+    limit: int,
+    offset: int,
+    order_by: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """The same page as `run_query`, as CSVWithNames text in `output`."""
+    s, err = await _gated_session(sid)
+    if s is None:
+        return err  # type: ignore[return-value]
+    r = await DRIVERS[s.type].export_csv(s.config, sql, s.database, limit, offset, order_by)
     if not r.ok:
         return {"ok": False, "message": r.value}
     return {"ok": True, "output": r.value}

{queryview-0.0.3 → queryview-0.0.4}/backend/queryview/dashboard_queries.py

@@ -9,27 +9,13 @@ from typing import Any
 
 from .connect import _connection_by_name
 from .drivers import DRIVERS
+from .drivers.base import rows_to_columns
 
 # Row cap per dashboard query (matches /api/clickhouse/query's ceiling), applied
 # as the LIMIT of the subselect wrapping each query.
 DASHBOARD_ROW_CAP = 1000
 
 
-def _parse_tsv_columns(text: str) -> dict[str, list[str]]:
-    """Parse TabSeparatedWithNames into a column-oriented, insertion-ordered dict
-    `{column_name: [values, …]}` (first line = names, rest = rows). Empty -> {}."""
-    if text == "":
-        return {}
-    lines = text.split("\n")
-    names = lines[0].split("\t")
-    cols: dict[str, list[str]] = {name: [] for name in names}
-    for line in lines[1:]:
-        values = line.split("\t")
-        for i, name in enumerate(names):
-            cols[name].append(values[i] if i < len(values) else "")
-    return cols
-
-
 async def run_queries_for_connection(
     name: str,
     queries: dict[str, str],
@@ -39,8 +25,9 @@ async def run_queries_for_connection(
     """Run a dashboard's named queries against a saved connection by name.
     Fail-fast: an unknown connection, no selected database, or the first failing
     query aborts the call. On full success returns {"ok": True, "results": {name:
-    {col: [values, …]}}} — column-oriented, ready for window.queries. `limit`/
-    `offset` page each query (default: the dashboard row cap, from row 0)."""
+    {col: [values, …]}}, "meta": {name: [{name, type}, …]}} — column-oriented,
+    ready for window.queries, values typed as the driver returned them.
+    `limit`/`offset` page each query (default: the dashboard row cap, from row 0)."""
     stored = await _connection_by_name(name)
     if stored is None:
         return {
@@ -58,18 +45,12 @@ async def run_queries_for_connection(
                 "or fully-qualify table names as db.table"
             ),
         }
-    results: dict[str, dict[str, list[str]]] = {}
+    results: dict[str, dict[str, list[Any]]] = {}
+    meta: dict[str, list[dict[str, str]]] = {}
     for qname, sql in queries.items():
-        r = await driver.run_query(
-            stored.config,
-            sql,
-            stored.database,
-            limit=limit,
-            offset=offset,
-            order_by=None,
-            fmt="tsv",
-        )
-        if not r.ok:
-            return {"ok": False, "reason": "query", "message": f"{qname}: {r.value}"}
-        results[qname] = _parse_tsv_columns(r.value)
-    return {"ok": True, "results": results}
+        r = await driver.run_query(stored.config, sql, stored.database, limit=limit, offset=offset, order_by=None)
+        if not r.ok or r.rows is None:
+            return {"ok": False, "reason": "query", "message": f"{qname}: {r.message}"}
+        results[qname] = rows_to_columns(r.rows)
+        meta[qname] = [c._asdict() for c in r.rows.meta]
+    return {"ok": True, "results": results, "meta": meta}

{queryview-0.0.3 → queryview-0.0.4}/backend/queryview/drivers/base.py

@@ -1,16 +1,40 @@
-"""The driver contract (Protocol) plus dialect helpers and the row serializer
-shared by row-returning drivers. No backend/storage concerns here."""
+"""The driver contract (Protocol) plus dialect helpers and the shared result
+contract: typed, JSON-safe rows for the UI and CSV text for download. No
+backend/storage concerns here."""
 
 from __future__ import annotations
 
 import csv
+import datetime as dt
 import io
+import math
+import uuid
+from decimal import Decimal
 from typing import Any, NamedTuple, Protocol, TypeAlias, runtime_checkable
 
 
+class Column(NamedTuple):
+    name: str
+    type: str  # the dialect's own type name (ClickHouse `UInt64`, Postgres `text`, …)
+
+
+class QueryRows(NamedTuple):
+    """A query result in ClickHouse's JSONCompact shape: column metadata plus
+    row-major values that are JSON-safe as-is (see `to_json_value`)."""
+
+    meta: list[Column]
+    data: list[list[Any]]
+
+
 class QueryResult(NamedTuple):
     ok: bool
-    value: str  # serialized rows when ok; an error message otherwise
+    rows: QueryRows | None = None  # set when ok
+    message: str = ""  # set when not ok
+
+
+class TextResult(NamedTuple):
+    ok: bool
+    value: str  # the text when ok; an error message otherwise
 
 
 # A driver's own config object (ChConfig, PgConfig, DuckConfig, …). Opaque to
@@ -56,8 +80,17 @@ class Driver(Protocol):
         limit: int,
         offset: int,
         order_by: list[dict[str, Any]] | None,
-        fmt: str,
     ) -> QueryResult: ...
+    # The same page as run_query, as CSVWithNames text for download.
+    async def export_csv(
+        self,
+        config: DriverConfig,
+        sql: str,
+        database: str | None,
+        limit: int,
+        offset: int,
+        order_by: list[dict[str, Any]] | None,
+    ) -> TextResult: ...
     async def describe_query(
         self,
         config: DriverConfig,
@@ -148,18 +181,53 @@ def wrap_paginated(
     return " ".join(clauses)
 
 
-def serialize_rows(columns: list[str], rows: list[Any], fmt: str) -> str:
-    """Serialize rows to the text contract ClickHouse emits: TabSeparatedWithNames
-    (fmt='tsv') or CSVWithNames (fmt='csv'). None -> empty field. Non-strings are
-    str()-ified. No trailing newline (matches ClickHouse's stripped output)."""
-    if fmt == "csv":
-        buf = io.StringIO()
-        writer = csv.writer(buf, lineterminator="\n")
-        writer.writerow(columns)
-        for row in rows:
-            writer.writerow(["" if v is None else str(v) for v in row])
-        return buf.getvalue().rstrip("\n")
-    lines = ["\t".join(columns)]
+# The largest integer a JS number holds exactly; beyond it values travel as strings.
+_JS_SAFE_INT = 2**53 - 1
+
+
+def to_json_value(v: Any) -> Any:
+    """A JSON-safe value that survives the browser: ints beyond 2^53, Decimals,
+    NaN/Inf, datetimes, UUIDs, and bytes become strings; containers recurse;
+    JSON scalars pass through. Mirrors what ClickHouse's JSONCompact emits
+    with 64-bit integers and decimals quoted, so every driver looks the same."""
+    if v is None or isinstance(v, (bool, str)):
+        return v
+    if isinstance(v, int):
+        return v if -_JS_SAFE_INT <= v <= _JS_SAFE_INT else str(v)
+    if isinstance(v, float):
+        return str(v) if math.isnan(v) or math.isinf(v) else v
+    if isinstance(v, Decimal):
+        return str(v)
+    if isinstance(v, (dt.datetime, dt.date, dt.time)):
+        return v.isoformat()
+    if isinstance(v, uuid.UUID):
+        return str(v)
+    if isinstance(v, (bytes, bytearray)):
+        return bytes(v).decode("utf-8", "replace")
+    if isinstance(v, (list, tuple, set, frozenset)):
+        return [to_json_value(x) for x in v]
+    if isinstance(v, dict):
+        return {str(k): to_json_value(x) for k, x in v.items()}
+    return str(v)
+
+
+def to_csv(columns: list[str], rows: list[Any]) -> str:
+    """CSVWithNames text as ClickHouse emits it: header row, LF line ends, None
+    as an empty field, no trailing newline."""
+    buf = io.StringIO()
+    writer = csv.writer(buf, lineterminator="\n")
+    writer.writerow(columns)
     for row in rows:
-        lines.append("\t".join("" if v is None else str(v) for v in row))
-    return "\n".join(lines)
+        writer.writerow(["" if v is None else str(v) for v in row])
+    return buf.getvalue().rstrip("\n")
+
+
+def rows_to_columns(rows: QueryRows) -> dict[str, list[Any]]:
+    """Column-oriented, insertion-ordered `{name: [values, …]}` — the dashboard
+    `window.queries` shape."""
+    cols: dict[str, list[Any]] = {c.name: [] for c in rows.meta}
+    names = [c.name for c in rows.meta]
+    for row in rows.data:
+        for i, name in enumerate(names):
+            cols[name].append(row[i] if i < len(row) else None)
+    return cols

{queryview-0.0.3 → queryview-0.0.4}/backend/queryview/drivers/clickhouse.py

@@ -2,12 +2,13 @@
 
 from __future__ import annotations
 
+import json
 from dataclasses import asdict, dataclass
 from typing import Any, NamedTuple
 
 import httpx
 
-from .base import QueryResult, build_order_by, parse_host_port_config, wrap_paginated
+from .base import Column, QueryResult, QueryRows, TextResult, build_order_by, parse_host_port_config, wrap_paginated
 
 CH_TIMEOUT_SECONDS = 5.0
 
@@ -25,12 +26,30 @@ class ChResult(NamedTuple):
     value: str
 
 
-async def ch_query(c: ChConfig, query: str, database: str | None = None, fmt: str | None = None) -> ChResult:
+# JSONCompact output settings: values a JS number would mangle are quoted by
+# ClickHouse itself, and named tuples arrive as objects so the UI can label
+# their fields.
+JSON_COMPACT_SETTINGS = {
+    "output_format_json_quote_64bit_integers": "1",
+    "output_format_json_quote_decimals": "1",
+    "output_format_json_quote_denormals": "1",
+    "output_format_json_named_tuples_as_objects": "1",
+}
+
+
+async def ch_query(
+    c: ChConfig,
+    query: str,
+    database: str | None = None,
+    fmt: str | None = None,
+    settings: dict[str, str] | None = None,
+) -> ChResult:
     """Run a query against the ClickHouse HTTP interface (Basic auth, 5s timeout).
-    `database` scopes the query; `fmt` appends a ClickHouse `FORMAT` clause."""
+    `database` scopes the query; `fmt` appends a ClickHouse `FORMAT` clause;
+    `settings` are passed as URL parameters."""
     url = f"http://{c.host}:{c.port}/"
     q = f"{query}\nFORMAT {fmt}" if fmt else query
-    params = {"query": q}
+    params = {"query": q, **(settings or {})}
     if database:
         params["database"] = database
     try:
@@ -120,13 +139,33 @@ class ClickHouseDriver:
         limit: int,
         offset: int,
         order_by: list[dict[str, Any]] | None,
-        fmt: str,
     ) -> QueryResult:
         order_clause = build_order_by(order_by, "`")
         paginated = wrap_paginated(sql, order_clause, limit, offset, alias=None)
-        ch_fmt = "CSVWithNames" if fmt == "csv" else "TabSeparatedWithNames"
-        r = await ch_query(config, paginated, database=database, fmt=ch_fmt)
-        return QueryResult(r.ok, r.value)
+        r = await ch_query(config, paginated, database=database, fmt="JSONCompact", settings=JSON_COMPACT_SETTINGS)
+        if not r.ok:
+            return QueryResult(False, None, r.value)
+        try:
+            doc = json.loads(r.value)
+            meta = [Column(str(m["name"]), str(m["type"])) for m in doc["meta"]]
+            data = [list(row) for row in doc["data"]]
+        except (ValueError, KeyError, TypeError) as err:
+            return QueryResult(False, None, f"unexpected JSON from ClickHouse: {err}")
+        return QueryResult(True, QueryRows(meta, data))
+
+    async def export_csv(
+        self,
+        config: ChConfig,
+        sql: str,
+        database: str | None,
+        limit: int,
+        offset: int,
+        order_by: list[dict[str, Any]] | None,
+    ) -> TextResult:
+        order_clause = build_order_by(order_by, "`")
+        paginated = wrap_paginated(sql, order_clause, limit, offset, alias=None)
+        r = await ch_query(config, paginated, database=database, fmt="CSVWithNames")
+        return TextResult(r.ok, r.value)
 
     async def describe_query(
         self, config: ChConfig, sql: str, database: str | None

{queryview-0.0.3 → queryview-0.0.4}/backend/queryview/drivers/duckdb.py

@@ -9,7 +9,7 @@ from typing import Any
 
 import duckdb
 
-from .base import QueryResult, build_order_by, serialize_rows, wrap_paginated
+from .base import Column, QueryResult, QueryRows, TextResult, build_order_by, to_csv, to_json_value, wrap_paginated
 
 
 @dataclass(frozen=True)
@@ -104,7 +104,7 @@ class DuckDBDriver:
         except Exception as e:  # noqa: BLE001
             return False, str(e)
 
-    async def run_query(
+    async def _fetch_page(
         self,
         config: DuckConfig,
         sql: str,
@@ -112,26 +112,50 @@ class DuckDBDriver:
         limit: int,
         offset: int,
         order_by: list[dict[str, Any]] | None,
-        fmt: str,
-    ) -> QueryResult:
+    ) -> QueryRows:
         order_clause = build_order_by(order_by, '"')
         paginated = wrap_paginated(sql, order_clause, limit, offset, alias="_qv")
 
-        def _work():
+        def _work() -> QueryRows:
             con = _open(config.path)
             try:
-                cur = con.execute(paginated)
-                columns = [d[0] for d in cur.description] if cur.description else []
-                rows = cur.fetchall()
-                return columns, rows
+                # A relation exposes DuckDB's own type names alongside the rows.
+                rel = con.sql(paginated)
+                meta = [Column(name, str(t)) for name, t in zip(rel.columns, rel.types, strict=True)]
+                return QueryRows(meta, [[to_json_value(v) for v in row] for row in rel.fetchall()])
             finally:
                 con.close()
 
+        return await asyncio.to_thread(_work)
+
+    async def run_query(
+        self,
+        config: DuckConfig,
+        sql: str,
+        database: str | None,
+        limit: int,
+        offset: int,
+        order_by: list[dict[str, Any]] | None,
+    ) -> QueryResult:
+        try:
+            return QueryResult(True, await self._fetch_page(config, sql, database, limit, offset, order_by))
+        except Exception as e:  # noqa: BLE001
+            return QueryResult(False, None, str(e))
+
+    async def export_csv(
+        self,
+        config: DuckConfig,
+        sql: str,
+        database: str | None,
+        limit: int,
+        offset: int,
+        order_by: list[dict[str, Any]] | None,
+    ) -> TextResult:
         try:
-            columns, rows = await asyncio.to_thread(_work)
-            return QueryResult(True, serialize_rows(columns, rows, fmt))
+            rows = await self._fetch_page(config, sql, database, limit, offset, order_by)
         except Exception as e:  # noqa: BLE001
-            return QueryResult(False, str(e))
+            return TextResult(False, str(e))
+        return TextResult(True, to_csv([c.name for c in rows.meta], rows.data))
 
     async def describe_query(
         self, config: DuckConfig, sql: str, database: str | None

{queryview-0.0.3 → queryview-0.0.4}/backend/queryview/drivers/postgres.py

@@ -10,10 +10,14 @@ from typing import Any
 import asyncpg
 
 from .base import (
+    Column,
     QueryResult,
+    QueryRows,
+    TextResult,
     build_order_by,
     parse_host_port_config,
-    serialize_rows,
+    to_csv,
+    to_json_value,
     wrap_paginated,
 )
 
@@ -133,7 +137,7 @@ class PostgresDriver:
         except Exception as e:  # noqa: BLE001
             return False, str(e) or "connection failed"
 
-    async def run_query(
+    async def _fetch_page(
         self,
         config: PgConfig,
         sql: str,
@@ -141,18 +145,43 @@ class PostgresDriver:
         limit: int,
         offset: int,
         order_by: list[dict[str, Any]] | None,
-        fmt: str,
-    ) -> QueryResult:
+    ) -> QueryRows:
         order_clause = build_order_by(order_by, '"')
         paginated = wrap_paginated(sql, order_clause, limit, offset, alias="_qv")
+        async with _connect(config, database) as conn:
+            stmt = await conn.prepare(paginated)
+            meta = [Column(a.name, a.type.name) for a in stmt.get_attributes()]
+            records = await stmt.fetch()
+            return QueryRows(meta, [[to_json_value(v) for v in r] for r in records])
+
+    async def run_query(
+        self,
+        config: PgConfig,
+        sql: str,
+        database: str | None,
+        limit: int,
+        offset: int,
+        order_by: list[dict[str, Any]] | None,
+    ) -> QueryResult:
         try:
-            async with _connect(config, database) as conn:
-                stmt = await conn.prepare(paginated)
-                columns = [a.name for a in stmt.get_attributes()]
-                records = await stmt.fetch()
-                return QueryResult(True, serialize_rows(columns, [list(r) for r in records], fmt))
+            return QueryResult(True, await self._fetch_page(config, sql, database, limit, offset, order_by))
+        except Exception as e:  # noqa: BLE001
+            return QueryResult(False, None, str(e) or "connection failed")
+
+    async def export_csv(
+        self,
+        config: PgConfig,
+        sql: str,
+        database: str | None,
+        limit: int,
+        offset: int,
+        order_by: list[dict[str, Any]] | None,
+    ) -> TextResult:
+        try:
+            rows = await self._fetch_page(config, sql, database, limit, offset, order_by)
         except Exception as e:  # noqa: BLE001
-            return QueryResult(False, str(e) or "connection failed")
+            return TextResult(False, str(e) or "connection failed")
+        return TextResult(True, to_csv([c.name for c in rows.meta], rows.data))
 
     async def describe_query(
         self, config: PgConfig, sql: str, database: str | None

queryview-0.0.4/backend/queryview/drivers/test_base.py

@@ -0,0 +1,85 @@
+"""Driver dialect helpers and the shared result contract (JSON-safe rows, CSV)."""
+
+from __future__ import annotations
+
+import datetime as dt
+import uuid
+from decimal import Decimal
+
+from queryview.drivers.base import (
+    Column,
+    QueryRows,
+    build_order_by,
+    rows_to_columns,
+    select_all_sql,
+    to_csv,
+    to_json_value,
+    wrap_paginated,
+)
+
+
+def test_select_all_sql_quotes_and_doubles_embedded_quotes():
+    assert select_all_sql("items", '"') == 'SELECT * FROM "items"'
+    assert select_all_sql('we"ird', '"') == 'SELECT * FROM "we""ird"'
+    assert select_all_sql("a`b", "`") == "SELECT * FROM `a``b`"
+
+
+def test_build_order_by_quotes_and_whitelists_direction():
+    assert build_order_by([{"name": "a", "dir": "desc"}], "`") == "ORDER BY `a` DESC"
+    # Unknown direction falls back to ASC; quote chars in the name are doubled.
+    assert build_order_by([{"name": "a`b", "dir": "x"}], "`") == "ORDER BY `a``b` ASC"
+    assert build_order_by([{"name": "a"}], '"') == 'ORDER BY "a" ASC'
+    assert build_order_by(None, "`") == ""
+    assert build_order_by([{"bad": 1}], "`") == ""
+
+
+def test_wrap_paginated_matches_clickhouse_shape_without_alias():
+    out = wrap_paginated("SELECT 1;", "", 100, 0, alias=None)
+    assert out == "SELECT * FROM (\nSELECT 1\n) LIMIT 100 OFFSET 0"
+
+
+def test_wrap_paginated_adds_alias_and_order():
+    out = wrap_paginated("SELECT 1", 'ORDER BY "a" ASC', 10, 5, alias="_qv")
+    assert out == 'SELECT * FROM (\nSELECT 1\n) AS _qv ORDER BY "a" ASC LIMIT 10 OFFSET 5'
+
+
+def test_to_json_value_keeps_json_scalars():
+    assert [to_json_value(v) for v in (None, True, 1, 1.5, "s")] == [None, True, 1, 1.5, "s"]
+
+
+def test_to_json_value_stringifies_values_json_would_mangle():
+    # Beyond 2^53 a JS number rounds; Decimal has no JSON type; NaN/Inf aren't JSON.
+    assert to_json_value(2**53) == "9007199254740992"
+    assert to_json_value(-(2**53)) == "-9007199254740992"
+    assert to_json_value(2**53 - 1) == 2**53 - 1
+    assert to_json_value(Decimal("1.10")) == "1.10"
+    assert to_json_value(float("nan")) == "nan"
+    assert to_json_value(float("-inf")) == "-inf"
+
+
+def test_to_json_value_formats_temporals_and_ids_as_strings():
+    assert to_json_value(dt.datetime(2024, 1, 2, 3, 4, 5)) == "2024-01-02T03:04:05"
+    assert to_json_value(dt.date(2024, 1, 2)) == "2024-01-02"
+    u = uuid.UUID("12345678-1234-5678-1234-567812345678")
+    assert to_json_value(u) == str(u)
+    assert to_json_value(b"\x00hi") == "\x00hi"
+
+
+def test_to_json_value_recurses_containers():
+    assert to_json_value((1, [Decimal("2"), None], {"k": (3,)})) == [1, ["2", None], {"k": [3]}]
+    assert to_json_value({1: "a"}) == {"1": "a"}
+
+
+def test_to_csv_quotes_and_uses_lf():
+    assert to_csv(["a", "b"], [["x,y", "z"]]) == 'a,b\n"x,y",z'
+
+
+def test_to_csv_nulls_are_empty_fields_and_empty_is_just_header():
+    assert to_csv(["id", "name"], [[1, None]]) == "id,name\n1,"
+    assert to_csv(["a"], []) == "a"
+
+
+def test_rows_to_columns_is_column_oriented_and_ordered():
+    rows = QueryRows([Column("a", "Int32"), Column("b", "String")], [[1, "x"], [2, "y"]])
+    assert rows_to_columns(rows) == {"a": [1, 2], "b": ["x", "y"]}
+    assert rows_to_columns(QueryRows([Column("a", "Int32")], [])) == {"a": []}

queryview-0.0.4/backend/queryview/drivers/test_clickhouse.py

@@ -0,0 +1,97 @@
+"""ClickHouse-specific behavior: run_query builds the historical paginated SQL
+(backtick-quoted, no subquery alias) and asks ClickHouse for JSONCompact. Registry conformance,
+config round-trip, and validation are covered by test_driver_contract."""
+
+from __future__ import annotations
+
+import asyncio
+
+from queryview.drivers.base import Column
+from queryview.drivers.clickhouse import ChConfig, ClickHouseDriver
+
+JSON_COMPACT = (
+    '{"meta":[{"name":"id","type":"UInt64"},{"name":"tags","type":"Array(String)"}],"data":[["1",["a","b"]]],"rows":1}'
+)
+
+
+def _capture(monkeypatch, seen, text):
+    async def fake_ch_query(c, query, database=None, fmt=None, settings=None):
+        from queryview.drivers.clickhouse import ChResult
+
+        seen.update(query=query, fmt=fmt, database=database, settings=settings)
+        return ChResult(True, text)
+
+    monkeypatch.setattr("queryview.drivers.clickhouse.ch_query", fake_ch_query)
+
+
+def test_run_query_builds_clickhouse_sql_and_parses_json_compact(monkeypatch):
+    d = ClickHouseDriver()
+    seen = {}
+    _capture(monkeypatch, seen, JSON_COMPACT)
+    r = asyncio.run(d.run_query(ChConfig("h", 1, "u", ""), "SELECT 1;", "db", 100, 0, [{"name": "a", "dir": "DESC"}]))
+    assert r.ok and r.rows is not None
+    assert r.rows.meta == [Column("id", "UInt64"), Column("tags", "Array(String)")]
+    assert r.rows.data == [["1", ["a", "b"]]]
+    assert seen["query"] == "SELECT * FROM (\nSELECT 1\n) ORDER BY `a` DESC LIMIT 100 OFFSET 0"
+    assert seen["fmt"] == "JSONCompact"
+    assert seen["database"] == "db"
+    # Values a JS number would mangle are quoted by ClickHouse itself; named
+    # tuples arrive as objects so the UI can label their fields.
+    assert seen["settings"] == {
+        "output_format_json_quote_64bit_integers": "1",
+        "output_format_json_quote_decimals": "1",
+        "output_format_json_quote_denormals": "1",
+        "output_format_json_named_tuples_as_objects": "1",
+    }
+
+
+def test_run_query_reports_driver_error(monkeypatch):
+    d = ClickHouseDriver()
+
+    async def fake_ch_query(c, query, database=None, fmt=None, settings=None):
+        from queryview.drivers.clickhouse import ChResult
+
+        return ChResult(False, "ClickHouse responded 400: boom")
+
+    monkeypatch.setattr("queryview.drivers.clickhouse.ch_query", fake_ch_query)
+    r = asyncio.run(d.run_query(ChConfig("h", 1, "u", ""), "SELECT 1", None, 10, 0, None))
+    assert r.ok is False and r.rows is None and "boom" in r.message
+
+
+def test_run_query_rejects_unparseable_body(monkeypatch):
+    d = ClickHouseDriver()
+    _capture(monkeypatch, {}, "not json")
+    r = asyncio.run(d.run_query(ChConfig("h", 1, "u", ""), "SELECT 1", None, 10, 0, None))
+    assert r.ok is False and "JSON" in r.message
+
+
+def test_export_csv_requests_csv_with_names(monkeypatch):
+    d = ClickHouseDriver()
+    seen = {}
+    _capture(monkeypatch, seen, "id,name\n1,a")
+    r = asyncio.run(d.export_csv(ChConfig("h", 1, "u", ""), "SELECT 1", "db", 5, 0, None))
+    assert r.ok and r.value == "id,name\n1,a"
+    assert seen["fmt"] == "CSVWithNames"
+    assert seen["query"] == "SELECT * FROM (\nSELECT 1\n) LIMIT 5 OFFSET 0"
+
+
+def test_list_tables_parses_rows_and_bytes_with_nulls(monkeypatch):
+    d = ClickHouseDriver()
+    seen = {}
+
+    async def fake_ch_query(c, query, database=None, fmt=None):
+        from queryview.drivers.clickhouse import ChResult
+
+        seen["query"] = query
+        seen["database"] = database
+        # A MergeTree table with stats and a view (\N for both counters).
+        return ChResult(True, "items\t3\t245\nv_items\t\\N\t\\N")
+
+    monkeypatch.setattr("queryview.drivers.clickhouse.ch_query", fake_ch_query)
+    ok, tables = asyncio.run(d.list_tables(ChConfig("h", 1, "u", ""), "db"))
+    assert ok and tables == [
+        {"name": "items", "rows": 3, "bytes": 245},
+        {"name": "v_items", "rows": None, "bytes": None},
+    ]
+    assert "system.tables" in seen["query"]
+    assert seen["database"] == "db"