queryview 0.0.2__py3-none-any.whl

queryview/drivers/postgres.py

@@ -0,0 +1,166 @@
+"""Postgres driver (asyncpg). Short-lived connections per request; the picker
+lists real databases and the selected one is where queries run."""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from dataclasses import asdict, dataclass
+from typing import Any
+
+import asyncpg
+
+from .base import (
+    QueryResult,
+    build_order_by,
+    parse_host_port_config,
+    serialize_rows,
+    wrap_paginated,
+)
+
+PG_TIMEOUT_SECONDS = 5
+_BOOTSTRAP_DBS = ("postgres", "template1")
+
+
+@dataclass(frozen=True)
+class PgConfig:
+    host: str
+    port: int
+    username: str
+    password: str
+
+
+def parse_pg_config(body: Any) -> tuple[PgConfig | None, str | None]:
+    fields, err = parse_host_port_config(body)
+    if err or fields is None:
+        return None, err
+    return PgConfig(**fields), None
+
+
+async def _raw_connect(c: PgConfig, database: str | None):
+    return await asyncpg.connect(
+        host=c.host,
+        port=c.port,
+        user=c.username or None,
+        password=c.password or None,
+        database=database,
+        timeout=PG_TIMEOUT_SECONDS,
+        command_timeout=PG_TIMEOUT_SECONDS,
+    )
+
+
+async def _raw_connect_bootstrap(c: PgConfig):
+    """Connect to *some* database so we can enumerate the rest."""
+    candidates = ([c.username] if c.username else []) + list(_BOOTSTRAP_DBS)
+    last: Exception | None = None
+    for db in candidates:
+        try:
+            return await _raw_connect(c, db)
+        except Exception as e:  # noqa: BLE001
+            last = e
+    raise last if last is not None else RuntimeError("could not connect")
+
+
+@asynccontextmanager
+async def _connect(c: PgConfig, database: str | None):
+    """Short-lived connection to a specific database, closed on exit."""
+    conn = await _raw_connect(c, database)
+    try:
+        yield conn
+    finally:
+        await conn.close()
+
+
+@asynccontextmanager
+async def _connect_bootstrap(c: PgConfig):
+    """Short-lived connection to a maintenance database, closed on exit."""
+    conn = await _raw_connect_bootstrap(c)
+    try:
+        yield conn
+    finally:
+        await conn.close()
+
+
+class PostgresDriver:
+    type: str = "postgres"
+    requires_database: bool = True
+    ident_quote: str = '"'
+
+    def parse_config(self, body: Any) -> tuple[PgConfig | None, str | None]:
+        return parse_pg_config(body)
+
+    def config_to_dict(self, config: PgConfig) -> dict[str, Any]:
+        return asdict(config)
+
+    def config_from_dict(self, data: dict[str, Any]) -> PgConfig:
+        return PgConfig(**data)
+
+    async def test(self, config: PgConfig) -> dict[str, Any]:
+        try:
+            async with _connect_bootstrap(config) as conn:
+                val = await conn.fetchval("SELECT 1")
+                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: PgConfig) -> tuple[bool, list[str] | str]:
+        try:
+            async with _connect_bootstrap(config) as conn:
+                rows = await conn.fetch(
+                    "SELECT datname FROM pg_database WHERE datallowconn AND NOT datistemplate ORDER BY datname"
+                )
+                return True, [r["datname"] for r in rows]
+        except Exception as e:  # noqa: BLE001
+            return False, str(e) or "connection failed"
+
+    async def list_tables(self, config: PgConfig, database: str | None) -> tuple[bool, list[dict[str, Any]] | str]:
+        # Tables and views of the public schema — what an unqualified name in
+        # the explorer's generated SELECT resolves to under the default
+        # search_path. Other schemas need explicit SQL on the query page.
+        # Row counts are the planner's reltuples estimate (-1 = never analyzed
+        # -> NULL, e.g. a freshly created table); size is on-disk relation size.
+        try:
+            async with _connect(config, database) as conn:
+                rows = await conn.fetch(
+                    "SELECT c.relname AS name, "
+                    "CASE WHEN c.reltuples < 0 THEN NULL "
+                    "ELSE c.reltuples::bigint END AS rows, "
+                    "pg_total_relation_size(c.oid) AS bytes "
+                    "FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace "
+                    "WHERE n.nspname = 'public' AND c.relkind IN ('r', 'p', 'v', 'm') "
+                    "ORDER BY c.relname"
+                )
+                return True, [{"name": r["name"], "rows": r["rows"], "bytes": r["bytes"]} for r in rows]
+        except Exception as e:  # noqa: BLE001
+            return False, str(e) or "connection failed"
+
+    async def run_query(
+        self,
+        config: PgConfig,
+        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")
+        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))
+        except Exception as e:  # noqa: BLE001
+            return QueryResult(False, str(e) or "connection failed")
+
+    async def describe_query(
+        self, config: PgConfig, sql: str, database: str | None
+    ) -> tuple[bool, list[dict[str, str]] | str]:
+        inner = sql.rstrip().rstrip(";")
+        try:
+            async with _connect(config, database) as conn:
+                stmt = await conn.prepare(inner)
+                return True, [{"name": a.name, "type": a.type.name} for a in stmt.get_attributes()]
+        except Exception as e:  # noqa: BLE001
+            return False, str(e) or "connection failed"

queryview/drivers/test_base.py

@@ -0,0 +1,49 @@
+"""Driver dialect helpers and the row serializer (the shared output contract)."""
+
+from __future__ import annotations
+
+from queryview.drivers.base import (
+    build_order_by,
+    select_all_sql,
+    serialize_rows,
+    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_serialize_rows_tsv_with_names_and_nulls():
+    out = serialize_rows(["id", "name"], [[1, "a"], [2, None]], "tsv")
+    assert out == "id\tname\n1\ta\n2\t"
+
+
+def test_serialize_rows_csv_quotes_and_uses_lf():
+    out = serialize_rows(["a", "b"], [["x,y", "z"]], "csv")
+    assert out == 'a,b\n"x,y",z'
+
+
+def test_serialize_rows_empty_is_just_header():
+    assert serialize_rows(["a"], [], "tsv") == "a"

queryview/drivers/test_clickhouse.py

@@ -0,0 +1,53 @@
+"""ClickHouse-specific behavior: run_query builds the historical paginated SQL
+(backtick-quoted, no subquery alias, FORMAT clause). Registry conformance,
+config round-trip, and validation are covered by test_driver_contract."""
+
+from __future__ import annotations
+
+import asyncio
+
+from queryview.drivers.clickhouse import ChConfig, ClickHouseDriver
+
+
+def test_run_query_builds_clickhouse_sql(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["fmt"] = fmt
+        seen["database"] = database
+        return ChResult(True, "ok")
+
+    monkeypatch.setattr("queryview.drivers.clickhouse.ch_query", fake_ch_query)
+    r = asyncio.run(
+        d.run_query(ChConfig("h", 1, "u", ""), "SELECT 1;", "db", 100, 0, [{"name": "a", "dir": "DESC"}], "tsv")
+    )
+    assert r.ok and r.value == "ok"
+    assert seen["query"] == "SELECT * FROM (\nSELECT 1\n) ORDER BY `a` DESC LIMIT 100 OFFSET 0"
+    assert seen["fmt"] == "TabSeparatedWithNames"
+    assert seen["database"] == "db"
+
+
+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"

queryview/drivers/test_contract.py

@@ -0,0 +1,77 @@
+"""Driver contract, parameterized across every registered driver. Adding a
+driver to the registry (with a SAMPLES entry) automatically extends these
+checks. Driver-specific behavior (dialect SQL, real-DB queries) lives in the
+per-driver test modules."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import pytest
+
+from queryview.drivers import DRIVERS, Driver
+from queryview.drivers.clickhouse import ChConfig
+from queryview.drivers.duckdb import DuckConfig
+from queryview.drivers.postgres import PgConfig
+
+
+@dataclass
+class DriverSample:
+    config: Any  # a representative config object
+    valid_body: dict  # a request body that parses to `config`
+    requires_database: bool
+
+
+# One sample per driver `type`. A network driver is identified by a `host` field
+# in its valid body (so host/port validation checks auto-apply to it).
+SAMPLES: dict[str, DriverSample] = {
+    "clickhouse": DriverSample(
+        ChConfig("h", 8123, "u", "p"),
+        {"host": "h", "port": "8123", "username": "u", "password": "p"},
+        requires_database=True,
+    ),
+    "postgres": DriverSample(
+        PgConfig("h", 5432, "u", "p"),
+        {"host": "h", "port": "5432", "username": "u", "password": "p"},
+        requires_database=True,
+    ),
+    "duckdb": DriverSample(
+        DuckConfig("/tmp/x.duckdb"),
+        {"path": "/tmp/x.duckdb"},
+        requires_database=False,
+    ),
+}
+
+ALL = sorted(DRIVERS)
+NETWORK = sorted(t for t, s in SAMPLES.items() if "host" in s.valid_body)
+
+
+def test_samples_cover_every_registered_driver():
+    assert set(SAMPLES) == set(DRIVERS), "add a SAMPLES entry for each driver"
+
+
+@pytest.mark.parametrize("type_", ALL)
+def test_protocol_type_and_requires_database(type_):
+    d = DRIVERS[type_]
+    assert isinstance(d, Driver)
+    assert d.type == type_
+    assert d.requires_database is SAMPLES[type_].requires_database
+
+
+@pytest.mark.parametrize("type_", ALL)
+def test_parse_valid_body_and_config_round_trip(type_):
+    d = DRIVERS[type_]
+    sample = SAMPLES[type_]
+    parsed, err = d.parse_config(sample.valid_body)
+    assert err is None and parsed == sample.config
+    assert d.config_from_dict(d.config_to_dict(sample.config)) == sample.config
+
+
+@pytest.mark.parametrize("type_", NETWORK)
+def test_network_driver_rejects_missing_host_and_bad_port(type_):
+    d = DRIVERS[type_]
+    assert d.parse_config({"port": 5432})[0] is None  # missing host
+    assert d.parse_config({"host": "h", "port": 0})[0] is None  # port too low
+    assert d.parse_config({"host": "h", "port": 99999})[0] is None  # too high
+    assert d.parse_config({"host": "h", "port": "x"})[0] is None  # non-numeric

queryview/drivers/test_duckdb.py

@@ -0,0 +1,80 @@
+"""DuckDB-specific behavior against a real temp-file database: the :memory:
+default, the empty (no-picker) database list, paginated+serialized queries,
+describe, and error reporting. Registry conformance, config round-trip, and
+validation are covered by test_driver_contract."""
+
+from __future__ import annotations
+
+import asyncio
+
+import duckdb
+import pytest
+
+from queryview.drivers.duckdb import DuckConfig, DuckDBDriver
+
+
+def _run(coro):
+    return asyncio.run(coro)
+
+
+@pytest.fixture
+def duck_path(tmp_path):
+    path = tmp_path / "qv.duckdb"
+    con = duckdb.connect(str(path))
+    con.execute("CREATE TABLE items (id INTEGER, name TEXT)")
+    con.execute("INSERT INTO items VALUES (1,'alpha'),(2,'beta'),(3,'gamma')")
+    con.close()
+    return str(path)
+
+
+def test_parse_config_defaults_blank_path_to_memory():
+    d = DuckDBDriver()
+    assert d.parse_config({"path": ""})[0] == DuckConfig(":memory:")
+    assert d.parse_config({"path": "/tmp/x.duckdb"})[0] == DuckConfig("/tmp/x.duckdb")
+
+
+def test_list_databases_is_empty(duck_path):
+    d = DuckDBDriver()
+    assert _run(d.list_databases(DuckConfig(duck_path))) == (True, [])
+
+
+def test_list_tables_names_seeded_table_with_estimates(duck_path):
+    d = DuckDBDriver()
+    # rows is duckdb_tables()'s estimated_size; bytes is storage blocks × block
+    # size (a small positive multiple of the 256KiB block for a tiny table).
+    ok, tables = _run(d.list_tables(DuckConfig(duck_path), None))
+    assert ok and isinstance(tables, list) and len(tables) == 1
+    t = tables[0]
+    assert t["name"] == "items" and t["rows"] == 3
+    assert isinstance(t["bytes"], int) and t["bytes"] > 0
+
+
+def test_run_query_paginates_and_serializes(duck_path):
+    d = DuckDBDriver()
+    r = _run(
+        d.run_query(
+            DuckConfig(duck_path),
+            "SELECT id, name FROM items ORDER BY id",
+            None,
+            2,
+            0,
+            [{"name": "name", "dir": "ASC"}],
+            "tsv",
+        )
+    )
+    assert r.ok
+    assert r.value == "id\tname\n1\talpha\n2\tbeta"
+
+
+def test_describe_query_returns_columns(duck_path):
+    d = DuckDBDriver()
+    ok, fields = _run(d.describe_query(DuckConfig(duck_path), "SELECT id, name FROM items", None))
+    assert ok and isinstance(fields, list)
+    names = [f["name"] for f in fields]
+    assert names == ["id", "name"]
+
+
+def test_run_query_error_is_reported(duck_path):
+    d = DuckDBDriver()
+    r = _run(d.run_query(DuckConfig(duck_path), "SELECT * FROM no_such", None, 10, 0, None, "tsv"))
+    assert r.ok is False and "no_such" in r.value

queryview/drivers/test_postgres.py

@@ -0,0 +1,80 @@
+"""Postgres-specific behavior: run_query builds double-quoted, `_qv`-aliased
+paginated SQL (asyncpg is monkeypatched — no server). Registry conformance,
+config round-trip, and validation are covered by test_driver_contract; live
+connect/query/describe by e2e."""
+
+from __future__ import annotations
+
+import asyncio
+
+from queryview.drivers.postgres import PgConfig, PostgresDriver
+
+
+def test_run_query_builds_aliased_double_quoted_sql(monkeypatch):
+    d = PostgresDriver()
+    captured = {}
+
+    class _Stmt:
+        def get_attributes(self):
+            class _A:
+                name = "name"
+
+                class type:  # noqa: N801
+                    name = "text"
+
+            return (_A(),)
+
+        async def fetch(self):
+            return [["alpha"]]
+
+    class _Conn:
+        async def prepare(self, sql):
+            captured["sql"] = sql
+            return _Stmt()
+
+        async def close(self):
+            pass
+
+    async def fake_connect(c, database):
+        captured["database"] = database
+        return _Conn()
+
+    monkeypatch.setattr("queryview.drivers.postgres._raw_connect", fake_connect)
+    r = asyncio.run(
+        d.run_query(
+            PgConfig("h", 5432, "u", ""), "SELECT name FROM t;", "mydb", 50, 10, [{"name": "name", "dir": "ASC"}], "tsv"
+        )
+    )
+    assert r.ok and r.value == "name\nalpha"
+    assert captured["database"] == "mydb"
+    assert captured["sql"] == ('SELECT * FROM (\nSELECT name FROM t\n) AS _qv ORDER BY "name" ASC LIMIT 50 OFFSET 10')
+
+
+def test_list_tables_queries_public_schema_with_estimates(monkeypatch):
+    d = PostgresDriver()
+    captured = {}
+
+    class _Conn:
+        async def fetch(self, sql):
+            captured["sql"] = sql
+            return [
+                {"name": "items", "rows": 3, "bytes": 16384},
+                {"name": "fresh", "rows": None, "bytes": 8192},  # never analyzed
+            ]
+
+        async def close(self):
+            pass
+
+    async def fake_connect(c, database):
+        captured["database"] = database
+        return _Conn()
+
+    monkeypatch.setattr("queryview.drivers.postgres._raw_connect", fake_connect)
+    ok, tables = asyncio.run(d.list_tables(PgConfig("h", 5432, "u", ""), "mydb"))
+    assert ok and tables == [
+        {"name": "items", "rows": 3, "bytes": 16384},
+        {"name": "fresh", "rows": None, "bytes": 8192},
+    ]
+    assert captured["database"] == "mydb"
+    assert "nspname = 'public'" in captured["sql"]
+    assert "reltuples" in captured["sql"] and "pg_total_relation_size" in captured["sql"]