queryview 0.0.2__py3-none-any.whl

queryview/dashboards.py

@@ -0,0 +1,156 @@
+"""Dashboard store: dashboards (HTML layout + named SQL queries) keyed by name
+within a workspace. Reuses connect.py's SQLite engine, mirroring queries.py.
+Also hosts the shared upsert-and-push helper that both the REST endpoint and
+the MCP tool call."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, ClassVar
+
+from sqlalchemy import UniqueConstraint
+from sqlmodel import Field, SQLModel, select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from . import remote
+from .connect import _engine_for_db, _ensure_schema, _now_ms
+
+
+class Dashboard(SQLModel, table=True):
+    __tablename__: ClassVar[str] = "dashboards"
+    __table_args__ = (UniqueConstraint("workspace_id", "name", name="uq_dashboards_ws_name"),)
+
+    id: int | None = Field(default=None, primary_key=True)
+    name: str = Field(index=True)  # unique per workspace, not globally
+    workspace_id: int  # owning workspace (workspaces.id)
+    connection: str  # connection name the queries run against
+    html: str  # agent-authored HTML document
+    queries: str  # JSON text: {query_name: SQL}
+    updated_at: int  # unix ms
+
+
+async def upsert_dashboards(items: list[dict[str, Any]], *, workspace_id: int) -> None:
+    """Upsert many dashboards — each a dict with `name`, `connection`, `html`
+    and a `queries` dict — in one transaction, keyed by (workspace, name).
+    `queries` is serialized to JSON text."""
+    await _ensure_schema()
+    async with AsyncSession(_engine_for_db()) as s:
+        for d in items:
+            row = (
+                await s.exec(
+                    select(Dashboard).where(Dashboard.name == d["name"], Dashboard.workspace_id == workspace_id)
+                )
+            ).first()
+            if row is None:
+                row = Dashboard(
+                    name=d["name"], workspace_id=workspace_id, connection="", html="", queries="", updated_at=0
+                )
+            row.connection = d["connection"]
+            row.html = d["html"]
+            row.queries = json.dumps(d["queries"])
+            row.updated_at = _now_ms()
+            s.add(row)
+        await s.commit()
+
+
+async def upsert_dashboard(
+    name: str, connection: str, html: str, queries: dict[str, str], *, workspace_id: int
+) -> None:
+    """Upsert a dashboard by (workspace, name); `queries` is serialized to JSON text."""
+    await upsert_dashboards(
+        [{"name": name, "connection": connection, "html": html, "queries": queries}], workspace_id=workspace_id
+    )
+
+
+def _payload(row: Dashboard) -> dict[str, Any]:
+    """A row's full payload with `queries` parsed back to a dict (leniently —
+    unparsable stored text degrades to an empty map)."""
+    try:
+        queries = json.loads(row.queries)
+    except (ValueError, TypeError):
+        queries = {}
+    return {
+        "name": row.name,
+        "connection": row.connection,
+        "html": row.html,
+        "queries": queries,
+    }
+
+
+async def get_dashboard(name: str, workspace_id: int) -> dict[str, Any] | None:
+    """A single dashboard with its `queries` parsed back to a dict, or None."""
+    await _ensure_schema()
+    async with AsyncSession(_engine_for_db()) as s:
+        row = (
+            await s.exec(select(Dashboard).where(Dashboard.name == name, Dashboard.workspace_id == workspace_id))
+        ).first()
+    return _payload(row) if row is not None else None
+
+
+async def list_dashboards(workspace_id: int) -> list[dict[str, Any]]:
+    """One workspace's dashboards ordered by name, without the html/queries payload."""
+    await _ensure_schema()
+    async with AsyncSession(_engine_for_db()) as s:
+        rows = (
+            await s.exec(select(Dashboard).where(Dashboard.workspace_id == workspace_id).order_by(Dashboard.name))
+        ).all()
+    return [{"name": r.name, "connection": r.connection, "updated_at": r.updated_at} for r in rows]
+
+
+async def list_dashboards_full(workspace_id: int) -> list[dict[str, Any]]:
+    """One workspace's dashboards ordered by name, with the full payload in
+    get_dashboard's shape (`queries` parsed to a dict). Used by the
+    whole-workspace YAML export."""
+    await _ensure_schema()
+    async with AsyncSession(_engine_for_db()) as s:
+        rows = (
+            await s.exec(select(Dashboard).where(Dashboard.workspace_id == workspace_id).order_by(Dashboard.name))
+        ).all()
+    return [_payload(r) for r in rows]
+
+
+def _dashboard_event(name: str, connection: str, html: str, queries: dict[str, str]) -> dict[str, Any]:
+    """The SSE payload the browser renders for a pushed dashboard."""
+    return {
+        "type": "dashboard",
+        "name": name,
+        "connection": connection,
+        "html": html,
+        "queries": queries,
+    }
+
+
+async def _push_dashboard(
+    name: str,
+    connection: str,
+    html: str,
+    queries: dict[str, str],
+    session_id: str | None,
+) -> tuple[bool, str]:
+    """Push a dashboard to a live session as a DRAFT — no persistence. Only the
+    user's Save (POST /api/dashboards) writes it to the store, mirroring how
+    push_query drafts a query for the user to Save. Returns (pushed, message);
+    no session_id -> (False, "no session")."""
+    if not session_id:
+        return False, "no session"
+    return remote.push(session_id, _dashboard_event(name, connection, html, queries))
+
+
+async def _upsert_and_push(
+    name: str,
+    connection: str,
+    html: str,
+    queries: dict[str, str],
+    session_id: str | None,
+    *,
+    workspace_id: int,
+) -> tuple[bool, bool, str]:
+    """Persist a dashboard, then (if `session_id` given) push it to that live
+    browser session. Returns (persisted, pushed, message). Push is best-effort:
+    an unknown/inactive session leaves it saved with pushed=False, per
+    remote.push's contract. Used by the REST endpoint (the user-Save path)."""
+    await upsert_dashboard(name, connection, html, queries, workspace_id=workspace_id)
+    if session_id:
+        ok, message = remote.push(session_id, _dashboard_event(name, connection, html, queries))
+        return True, ok, message
+    return True, False, "persisted"

queryview/drivers/__init__.py

@@ -0,0 +1,10 @@
+"""Driver registry: maps a connection `type` to the Driver that executes it."""
+
+from __future__ import annotations
+
+from .base import Driver
+from .clickhouse import ClickHouseDriver
+from .duckdb import DuckDBDriver
+from .postgres import PostgresDriver
+
+DRIVERS: dict[str, Driver] = {d.type: d for d in (ClickHouseDriver(), PostgresDriver(), DuckDBDriver())}

queryview/drivers/base.py

@@ -0,0 +1,165 @@
+"""The driver contract (Protocol) plus dialect helpers and the row serializer
+shared by row-returning drivers. No backend/storage concerns here."""
+
+from __future__ import annotations
+
+import csv
+import io
+from typing import Any, NamedTuple, Protocol, TypeAlias, runtime_checkable
+
+
+class QueryResult(NamedTuple):
+    ok: bool
+    value: str  # serialized rows when ok; an error message otherwise
+
+
+# A driver's own config object (ChConfig, PgConfig, DuckConfig, …). Opaque to
+# everything outside the driver that produced it: the storage and session layers
+# only ever round-trip it back through the same driver's methods, so they must
+# NOT depend on any concrete type. Named (rather than a bare `Any`) so that
+# opacity is intentional and documented at every use site. A union of the
+# concrete configs would instead re-couple connect.py to every driver and defeat
+# the registry indirection.
+DriverConfig: TypeAlias = Any
+
+
+@runtime_checkable
+class Driver(Protocol):
+    # Stable identifier, also the registry key, the persisted `connections.type`
+    # column, and the API `type` field — one word across the whole stack.
+    type: str
+    # Whether queries require a database to be selected first (a non-empty
+    # picker). False for file-based drivers like DuckDB that have no picker.
+    requires_database: bool
+    # The dialect's identifier-quote character, for SQL generated server-side
+    # (select_all_sql). Same convention as the build_order_by `quote` argument.
+    ident_quote: str
+
+    def parse_config(self, body: Any) -> tuple[DriverConfig | None, str | None]: ...
+    def config_to_dict(self, config: DriverConfig) -> dict[str, Any]: ...
+    def config_from_dict(self, data: dict[str, Any]) -> DriverConfig: ...
+    async def test(self, config: DriverConfig) -> dict[str, Any]: ...
+    async def list_databases(self, config: DriverConfig) -> tuple[bool, list[str] | str]: ...
+    # Each table is {"name": str, "rows": int|None, "bytes": int|None} — rows and
+    # bytes are cheap engine estimates (never a COUNT(*) scan), None when the
+    # engine doesn't track them (e.g. views, or DuckDB's missing per-table size).
+    async def list_tables(
+        self,
+        config: DriverConfig,
+        database: str | None,
+    ) -> tuple[bool, list[dict[str, Any]] | str]: ...
+    async def run_query(
+        self,
+        config: DriverConfig,
+        sql: str,
+        database: str | None,
+        limit: int,
+        offset: int,
+        order_by: list[dict[str, Any]] | None,
+        fmt: str,
+    ) -> QueryResult: ...
+    async def describe_query(
+        self,
+        config: DriverConfig,
+        sql: str,
+        database: str | None,
+    ) -> tuple[bool, list[dict[str, str]] | str]: ...
+
+
+def _parse_port(raw: Any) -> int | None:
+    """Coerce a raw port value to an int in [1, 65535], or None. Rejects bool
+    (a bool is an int subclass) and out-of-range / non-numeric values."""
+    if isinstance(raw, bool) or not isinstance(raw, (int, str)):
+        return None
+    try:
+        port = int(raw)
+    except ValueError:
+        return None
+    return port if 1 <= port <= 65535 else None
+
+
+def parse_host_port_config(body: Any) -> tuple[dict[str, Any] | None, str | None]:
+    """Validate the host/port/username/password fields shared by network drivers
+    (ClickHouse, Postgres). Returns ({host,port,username,password}, None) or
+    (None, message)."""
+    b = body if isinstance(body, dict) else {}
+    raw_host = b.get("host")
+    host = raw_host.strip() if isinstance(raw_host, str) else ""
+    port = _parse_port(b.get("port"))
+    username = b.get("username") if isinstance(b.get("username"), str) else ""
+    password = b.get("password") if isinstance(b.get("password"), str) else ""
+    if not host:
+        return None, "host required"
+    if port is None:
+        return None, "valid port required"
+    return {"host": host, "port": port, "username": username, "password": password}, None
+
+
+def select_all_sql(table: str, quote: str) -> str:
+    """`SELECT * FROM <quoted table>` — the query the explorer browses a table
+    with. The name is `quote`-quoted with embedded quotes doubled, so an odd
+    table name can't escape the identifier."""
+    escaped = table.replace(quote, quote + quote)
+    return f"SELECT * FROM {quote}{escaped}{quote}"
+
+
+def build_order_by(order_by: list[dict[str, Any]] | None, quote: str) -> str:
+    """`ORDER BY` clause from `[{"name","dir"}]`. Names are `quote`-quoted (any
+    embedded quote doubled) and directions whitelisted to ASC/DESC, so malformed
+    input can't inject SQL. Empty/absent input yields no clause."""
+    if not order_by:
+        return ""
+    parts: list[str] = []
+    for col in order_by:
+        if not isinstance(col, dict):
+            continue
+        name = col.get("name")
+        if not isinstance(name, str) or not name:
+            continue
+        raw_dir = col.get("dir")
+        direction = raw_dir.upper() if isinstance(raw_dir, str) else ""
+        if direction not in ("ASC", "DESC"):
+            direction = "ASC"
+        escaped = name.replace(quote, quote + quote)
+        parts.append(f"{quote}{escaped}{quote} {direction}")
+    if not parts:
+        return ""
+    return "ORDER BY " + ", ".join(parts)
+
+
+def wrap_paginated(
+    sql: str,
+    order_clause: str,
+    limit: int,
+    offset: int,
+    alias: str | None = None,
+) -> str:
+    """Wrap a SELECT in a paginating subselect. `alias` (e.g. `_qv`) is required
+    by Postgres/DuckDB for a derived table; ClickHouse passes alias=None to keep
+    its historical SQL byte-for-byte identical."""
+    inner = sql.rstrip().rstrip(";")
+    head = f"SELECT * FROM (\n{inner}\n)"
+    if alias:
+        head += f" AS {alias}"
+    clauses = [head]
+    if order_clause:
+        clauses.append(order_clause)
+    clauses.append(f"LIMIT {int(limit)} OFFSET {int(offset)}")
+    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)]
+    for row in rows:
+        lines.append("\t".join("" if v is None else str(v) for v in row))
+    return "\n".join(lines)

queryview/drivers/clickhouse.py

@@ -0,0 +1,138 @@
+"""ClickHouse driver: the HTTP-interface client and a Driver implementation."""
+
+from __future__ import annotations
+
+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
+
+CH_TIMEOUT_SECONDS = 5.0
+
+
+@dataclass(frozen=True)
+class ChConfig:
+    host: str
+    port: int
+    username: str
+    password: str
+
+
+class ChResult(NamedTuple):
+    ok: bool
+    value: str
+
+
+async def ch_query(c: ChConfig, query: str, database: str | None = None, fmt: 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."""
+    url = f"http://{c.host}:{c.port}/"
+    q = f"{query}\nFORMAT {fmt}" if fmt else query
+    params = {"query": q}
+    if database:
+        params["database"] = database
+    try:
+        async with httpx.AsyncClient(timeout=CH_TIMEOUT_SECONDS) as client:
+            res = await client.get(url, params=params, auth=(c.username, c.password))
+    except httpx.TimeoutException:
+        return ChResult(False, "connection timed out")
+    except httpx.HTTPError as err:
+        return ChResult(False, str(err) or "connection failed")
+    text = res.text.strip()
+    if not res.is_success:
+        return ChResult(False, f"ClickHouse responded {res.status_code}: {text[:200]}")
+    return ChResult(True, text)
+
+
+def parse_ch_config(body: Any) -> tuple[ChConfig | None, str | None]:
+    """Validate a ClickHouse config from a request body. Returns (config, None) or
+    (None, message)."""
+    fields, err = parse_host_port_config(body)
+    if err or fields is None:
+        return None, err
+    return ChConfig(**fields), None
+
+
+def _tsv_rows(text: str, min_cols: int):
+    """Rows of a TabSeparated result: blank lines and rows with fewer than
+    `min_cols` columns are skipped."""
+    for line in text.split("\n"):
+        if not line.strip():
+            continue
+        cols = line.split("\t")
+        if len(cols) >= min_cols:
+            yield cols
+
+
+class ClickHouseDriver:
+    type: str = "clickhouse"
+    requires_database: bool = True
+    ident_quote: str = "`"
+
+    def parse_config(self, body: Any) -> tuple[ChConfig | None, str | None]:
+        return parse_ch_config(body)
+
+    def config_to_dict(self, config: ChConfig) -> dict[str, Any]:
+        return asdict(config)
+
+    def config_from_dict(self, data: dict[str, Any]) -> ChConfig:
+        return ChConfig(**data)
+
+    async def test(self, config: ChConfig) -> dict[str, Any]:
+        r = await ch_query(config, "SELECT 1")
+        if r.ok:
+            return {"ok": True, "message": f"Connected — SELECT 1 returned {r.value}"}
+        return {"ok": False, "message": r.value}
+
+    async def list_databases(self, config: ChConfig) -> tuple[bool, list[str] | str]:
+        r = await ch_query(config, "SHOW DATABASES")
+        if not r.ok:
+            return False, r.value
+        return True, [s.strip() for s in r.value.split("\n") if s.strip()]
+
+    async def list_tables(self, config: ChConfig, database: str | None) -> tuple[bool, list[dict[str, Any]] | str]:
+        # Same set SHOW TABLES yields, plus the engine's stored row/byte counts
+        # (NULL — serialized as \N — for views and engines that don't track them).
+        r = await ch_query(
+            config,
+            "SELECT name, total_rows, total_bytes FROM system.tables WHERE database = currentDatabase() ORDER BY name",
+            database=database,
+            fmt="TabSeparated",
+        )
+        if not r.ok:
+            return False, r.value
+        return True, [
+            {
+                "name": cols[0],
+                "rows": None if cols[1] == "\\N" else int(cols[1]),
+                "bytes": None if cols[2] == "\\N" else int(cols[2]),
+            }
+            for cols in _tsv_rows(r.value, 3)
+        ]
+
+    async def run_query(
+        self,
+        config: ChConfig,
+        sql: str,
+        database: str | None,
+        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)
+
+    async def describe_query(
+        self, config: ChConfig, sql: str, database: str | None
+    ) -> tuple[bool, list[dict[str, str]] | str]:
+        inner = sql.rstrip().rstrip(";")
+        r = await ch_query(config, f"DESCRIBE (\n{inner}\n)", database=database, fmt="TabSeparated")
+        if not r.ok:
+            return False, r.value
+        return True, [{"name": cols[0], "type": cols[1]} for cols in _tsv_rows(r.value, 2)]

queryview/drivers/duckdb.py

@@ -0,0 +1,153 @@
+"""DuckDB driver: file-based, no network, no picker. The synchronous duckdb
+library is driven in a worker thread so the event loop is never blocked."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import asdict, dataclass
+from typing import Any
+
+import duckdb
+
+from .base import QueryResult, build_order_by, serialize_rows, wrap_paginated
+
+
+@dataclass(frozen=True)
+class DuckConfig:
+    path: str
+
+
+def parse_duck_config(body: Any) -> tuple[DuckConfig | None, str | None]:
+    b = body if isinstance(body, dict) else {}
+    raw = b.get("path")
+    path = raw.strip() if isinstance(raw, str) else ""
+    return DuckConfig(path=path or ":memory:"), None
+
+
+def _open(path: str):
+    # read_only avoids lock contention between concurrent describe/query opens;
+    # :memory: cannot be read_only, so open it read-write.
+    return duckdb.connect(path, read_only=(path != ":memory:"))
+
+
+def _scalar(con: duckdb.DuckDBPyConnection, sql: str) -> Any:
+    """First column of the single-row result; raises if the query yields no row."""
+    row = con.execute(sql).fetchone()
+    if row is None:
+        raise RuntimeError(f"query returned no row: {sql}")
+    return row[0]
+
+
+class DuckDBDriver:
+    type: str = "duckdb"
+    requires_database: bool = False
+    ident_quote: str = '"'
+
+    def parse_config(self, body: Any) -> tuple[DuckConfig | None, str | None]:
+        return parse_duck_config(body)
+
+    def config_to_dict(self, config: DuckConfig) -> dict[str, Any]:
+        return asdict(config)
+
+    def config_from_dict(self, data: dict[str, Any]) -> DuckConfig:
+        return DuckConfig(**data)
+
+    async def test(self, config: DuckConfig) -> dict[str, Any]:
+        def _work():
+            con = _open(config.path)
+            try:
+                return _scalar(con, "SELECT 1")
+            finally:
+                con.close()
+
+        try:
+            val = await asyncio.to_thread(_work)
+            return {"ok": True, "message": f"Connected — SELECT 1 returned {val}"}
+        except Exception as e:  # noqa: BLE001
+            return {"ok": False, "message": str(e) or "connection failed"}
+
+    async def list_databases(self, config: DuckConfig) -> tuple[bool, list[str] | str]:
+        # No picker: queries run directly against the file (schema-qualify in SQL).
+        return True, []
+
+    async def list_tables(self, config: DuckConfig, database: str | None) -> tuple[bool, list[dict[str, Any]] | str]:
+        # SHOW TABLES for the name set, joined with duckdb_tables()'s estimated
+        # row count (absent for views). Bytes are distinct storage blocks ×
+        # block size from pragma_storage_info — metadata only, no data scan;
+        # None for views and whenever the pragma has nothing (e.g. :memory:).
+        def _work():
+            con = _open(config.path)
+            try:
+                names = [r[0] for r in con.execute("SHOW TABLES").fetchall()]
+                est = dict(con.execute("SELECT table_name, estimated_size FROM duckdb_tables()").fetchall())
+                block_size = _scalar(con, "SELECT block_size FROM pragma_database_size()")
+
+                def _bytes(name: str) -> int | None:
+                    if name not in est:  # a view — no storage of its own
+                        return None
+                    quoted = name.replace("'", "''")
+                    try:
+                        blocks = _scalar(
+                            con,
+                            f"SELECT count(DISTINCT block_id) FROM pragma_storage_info('{quoted}') WHERE block_id >= 0",
+                        )
+                    except Exception:  # noqa: BLE001
+                        return None
+                    return blocks * block_size if blocks else None
+
+                return [{"name": n, "rows": est.get(n), "bytes": _bytes(n)} for n in names]
+            finally:
+                con.close()
+
+        try:
+            return True, await asyncio.to_thread(_work)
+        except Exception as e:  # noqa: BLE001
+            return False, str(e)
+
+    async def run_query(
+        self,
+        config: DuckConfig,
+        sql: str,
+        database: str | None,
+        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="_qv")
+
+        def _work():
+            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
+            finally:
+                con.close()
+
+        try:
+            columns, rows = await asyncio.to_thread(_work)
+            return QueryResult(True, serialize_rows(columns, rows, fmt))
+        except Exception as e:  # noqa: BLE001
+            return QueryResult(False, str(e))
+
+    async def describe_query(
+        self, config: DuckConfig, sql: str, database: str | None
+    ) -> tuple[bool, list[dict[str, str]] | str]:
+        inner = sql.rstrip().rstrip(";")
+
+        def _work():
+            con = _open(config.path)
+            try:
+                # DuckDB's DESCRIBE returns (column_name, column_type, ...).
+                return con.execute(f"DESCRIBE {inner}").fetchall()
+            finally:
+                con.close()
+
+        try:
+            rows = await asyncio.to_thread(_work)
+            return True, [{"name": r[0], "type": r[1]} for r in rows]
+        except Exception as e:  # noqa: BLE001
+            return False, str(e)