jusi-postgres 0.2.0__py3-none-any.whl

jusi_postgres/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.2.0"

jusi_postgres/catalog.py

@@ -0,0 +1,19 @@
+"""Lightweight Jusi 1.0 catalog provider; imports no runtime dependencies."""
+from __future__ import annotations
+
+from typing import Any
+
+from jusi_sql import sql_catalog_entry
+
+from . import __version__
+
+
+def catalog_entry() -> dict[str, Any]:
+    return sql_catalog_entry(
+        plugin_id="postgres",
+        plugin_version=__version__,
+        distribution="jusi-postgres",
+        kernel_extension="jusi_postgres.kernel",
+        worker_entry_point="jusi_postgres.worker:create_worker",
+        provider_presentation={"syntax": "pgsql", "indent": "sql"},
+    )

jusi_postgres/config.py

@@ -0,0 +1,107 @@
+from __future__ import annotations
+
+import os
+from contextlib import contextmanager
+from dataclasses import dataclass
+from typing import Any, Iterator, Mapping
+
+
+PLUGIN_OPTIONS = {
+    "provider",
+    "initial_fetch",
+    "krb5ccname",
+    "collect_metadata",
+    "skip_metadata",
+    "metadata_max_rows",
+    "metadata_schemas",
+}
+
+DEFAULT_METADATA_MAX_ROWS = 1_000_000
+
+
+@dataclass(frozen=True)
+class PostgresOptions:
+    connect: dict[str, Any]
+    initial_fetch: int
+    krb5ccname: str
+    collect_metadata: bool
+    metadata_max_rows: int
+    metadata_schemas: tuple[str, ...]
+
+
+def parse_postgres_options(options: Mapping[str, Any]) -> PostgresOptions:
+    raw_initial = options.get("initial_fetch", 100)
+    try:
+        initial_fetch = int(raw_initial)
+    except (TypeError, ValueError):
+        initial_fetch = 100
+    if initial_fetch < 0:
+        initial_fetch = 0
+    krb5ccname = str(options.get("krb5ccname", "")).strip()
+    collect_metadata = _parse_bool(options.get("collect_metadata", True), default=True)
+    if _parse_bool(options.get("skip_metadata", False), default=False):
+        collect_metadata = False
+    raw_metadata_max_rows = options.get("metadata_max_rows", DEFAULT_METADATA_MAX_ROWS)
+    try:
+        metadata_max_rows = int(raw_metadata_max_rows)
+    except (TypeError, ValueError):
+        metadata_max_rows = DEFAULT_METADATA_MAX_ROWS
+    if metadata_max_rows < 1:
+        metadata_max_rows = DEFAULT_METADATA_MAX_ROWS
+    metadata_schemas = _parse_metadata_schemas(options.get("metadata_schemas", ()))
+    connect = {str(key): value for key, value in options.items() if str(key) not in PLUGIN_OPTIONS}
+    return PostgresOptions(
+        connect=connect,
+        initial_fetch=initial_fetch,
+        krb5ccname=krb5ccname,
+        collect_metadata=collect_metadata,
+        metadata_max_rows=metadata_max_rows,
+        metadata_schemas=metadata_schemas,
+    )
+
+
+def _parse_bool(value: Any, *, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    if value is None:
+        return default
+    normalized = str(value).strip().lower()
+    if normalized in {"1", "true", "yes", "on"}:
+        return True
+    if normalized in {"0", "false", "no", "off"}:
+        return False
+    return default
+
+
+def _parse_metadata_schemas(value: Any) -> tuple[str, ...]:
+    if isinstance(value, str):
+        raw_items = value.split(",")
+    elif isinstance(value, (list, tuple, set)):
+        raw_items = list(value)
+    else:
+        raw_items = []
+    schemas: list[str] = []
+    seen: set[str] = set()
+    for item in raw_items:
+        schema = str(item).strip()
+        if not schema or schema in seen:
+            continue
+        seen.add(schema)
+        schemas.append(schema)
+    return tuple(schemas)
+
+
+@contextmanager
+def kerberos_cache_env(path: str) -> Iterator[None]:
+    if not path:
+        yield
+        return
+    previous = os.environ.get("KRB5CCNAME")
+    os.environ["KRB5CCNAME"] = path
+    try:
+        yield
+    finally:
+        if previous is None:
+            os.environ.pop("KRB5CCNAME", None)
+        else:
+            os.environ["KRB5CCNAME"] = previous

jusi_postgres/constants.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+POSTGRES_BOOTSTRAP_SQL = "SELECT 1 AS jusi_bootstrap WHERE false"

jusi_postgres/ipc.py

@@ -0,0 +1,129 @@
+"""Private worker/application control channel for one PostgreSQL client."""
+from __future__ import annotations
+
+import json
+import os
+import socket
+import threading
+from typing import Any, Callable
+from uuid import uuid4
+
+
+class WorkerApplicationBridge:
+    def __init__(self, socket_path: str) -> None:
+        self.socket_path = socket_path
+        self._listener = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self._listener.bind(socket_path)
+        self._listener.listen(1)
+        self._connection: socket.socket | None = None
+        self._connected = threading.Event()
+        self._closed = threading.Event()
+        self._write_lock = threading.Lock()
+        self._condition = threading.Condition()
+        self._responses: dict[str, dict[str, Any]] = {}
+        threading.Thread(target=self._accept, name="jusi-postgres-bridge", daemon=True).start()
+
+    def _accept(self) -> None:
+        try:
+            connection, _ = self._listener.accept()
+            self._connection = connection
+            self._connected.set()
+            with connection.makefile("r", encoding="utf-8") as stream:
+                for line in stream:
+                    response = json.loads(line)
+                    request_id = str(response.get("id", ""))
+                    if request_id:
+                        with self._condition:
+                            self._responses[request_id] = response
+                            self._condition.notify_all()
+        except (OSError, ValueError, json.JSONDecodeError):
+            pass
+        finally:
+            self._closed.set()
+            self._connected.set()
+            with self._condition:
+                self._condition.notify_all()
+
+    def request(self, operation: str, payload: dict[str, Any]) -> dict[str, Any]:
+        if not self._connected.wait(10) or self._connection is None:
+            raise RuntimeError("PostgreSQL terminal application did not connect")
+        request_id = uuid4().hex
+        self._send({"id": request_id, "operation": operation, "payload": payload})
+        with self._condition:
+            while request_id not in self._responses and not self._closed.is_set():
+                self._condition.wait()
+            response = self._responses.pop(request_id, None)
+        if response is None:
+            raise RuntimeError("PostgreSQL terminal application disconnected")
+        return response
+
+    def interrupt(self) -> None:
+        if self._connection is not None and not self._closed.is_set():
+            self._send({"id": uuid4().hex, "operation": "interrupt", "payload": {}})
+
+    def _send(self, message: dict[str, Any]) -> None:
+        connection = self._connection
+        if connection is None:
+            raise RuntimeError("PostgreSQL terminal application is unavailable")
+        data = (json.dumps(message, ensure_ascii=False) + "\n").encode("utf-8")
+        with self._write_lock:
+            connection.sendall(data)
+
+    def close(self) -> None:
+        self._closed.set()
+        try:
+            self._listener.close()
+        except OSError:
+            pass
+        if self._connection is not None:
+            try:
+                self._connection.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+            self._connection.close()
+        try:
+            os.unlink(self.socket_path)
+        except FileNotFoundError:
+            pass
+        with self._condition:
+            self._condition.notify_all()
+
+
+class ApplicationController:
+    def __init__(self, socket_path: str, handler: Callable[[str, dict[str, Any]], dict[str, Any]]) -> None:
+        self._handler = handler
+        self._connection = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        self._connection.connect(socket_path)
+        self._write_lock = threading.Lock()
+
+    def start(self) -> None:
+        threading.Thread(target=self._read, name="jusi-postgres-control", daemon=True).start()
+
+    def _read(self) -> None:
+        try:
+            with self._connection.makefile("r", encoding="utf-8") as stream:
+                for line in stream:
+                    message = json.loads(line)
+                    operation = str(message.get("operation", ""))
+                    if operation == "interrupt":
+                        self._handle(message)
+                    else:
+                        threading.Thread(target=self._handle, args=(message,), daemon=True).start()
+        except (OSError, ValueError, json.JSONDecodeError):
+            return
+
+    def _handle(self, message: dict[str, Any]) -> None:
+        payload = message.get("payload", {})
+        if not isinstance(payload, dict):
+            payload = {}
+        try:
+            result = self._handler(str(message.get("operation", "")), payload)
+            response = {"ok": True, "result": result}
+        except BaseException as exc:
+            response = {"ok": False, "error": "fatal", "message": f"{type(exc).__name__}: {exc}"}
+        response = {"id": str(message.get("id", "")), **response}
+        try:
+            with self._write_lock:
+                self._connection.sendall((json.dumps(response, ensure_ascii=False) + "\n").encode("utf-8"))
+        except OSError:
+            return

jusi_postgres/kernel.py

@@ -0,0 +1,19 @@
+"""Thin exact-provider adapter for the shared Jusi SQL kernel dispatcher."""
+from __future__ import annotations
+
+from jusi_sql.kernel import SqlKernelAdapter
+
+from . import __version__
+from .constants import POSTGRES_BOOTSTRAP_SQL
+
+
+_adapter = SqlKernelAdapter(
+    plugin_id="postgres",
+    plugin_version=__version__,
+    selectors=("postgres", "postgresql"),
+    empty_sql=POSTGRES_BOOTSTRAP_SQL,
+)
+
+jusi_kernel_adapter_v1 = _adapter.manifest
+configure_jusi_runtime_v1 = _adapter.configure
+load_ipython_extension = _adapter.load

jusi_postgres/metadata.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from typing import Any, Iterable, Sequence
+
+from jusi_sql import CompletionColumn, CompletionObject, MetadataSnapshot
+
+
+class MetadataLimitExceeded(RuntimeError):
+    pass
+
+
+def load_postgres_metadata(
+    conn: Any,
+    *,
+    max_rows: int = 1_000_000,
+    schemas: Sequence[str] = (),
+) -> MetadataSnapshot:
+    collector = _BoundedMetadataCollector(max_rows=max_rows, schemas=schemas)
+    with conn.cursor() as cur:
+        cur.execute(*collector.query("SELECT nspname FROM pg_namespace", "nspname"))
+        schema_names = sorted(str(row[0]) for row in collector.fetch(cur, "schemas"))
+        cur.execute(
+            *collector.query(
+                """
+                SELECT n.nspname, c.relname, c.relkind
+                FROM pg_class c
+                JOIN pg_namespace n ON n.oid = c.relnamespace
+                """,
+                "n.nspname",
+                extra_predicates=("c.relkind IN ('r', 'p', 'v', 'm', 'f')",),
+            )
+        )
+        objects = [
+            CompletionObject(schema=str(row[0]), name=str(row[1]), kind=_relation_kind(str(row[2])))
+            for row in collector.fetch(cur, "relations")
+        ]
+        objects.sort(key=lambda item: (item.schema, item.name, item.kind))
+        cur.execute(
+            *collector.query(
+                """
+                SELECT table_schema, table_name, column_name, data_type
+                FROM information_schema.columns
+                """,
+                "table_schema",
+            )
+        )
+        columns = [
+            CompletionColumn(schema=str(row[0]), table=str(row[1]), name=str(row[2]), data_type=str(row[3]))
+            for row in collector.fetch(cur, "columns")
+        ]
+        columns.sort(key=lambda item: (item.schema, item.table, item.name))
+        cur.execute(
+            *collector.query(
+                """
+                SELECT n.nspname, p.proname, pg_get_function_identity_arguments(p.oid)
+                FROM pg_proc p
+                JOIN pg_namespace n ON n.oid = p.pronamespace
+                """,
+                "n.nspname",
+            )
+        )
+        functions = [
+            CompletionObject(schema=str(row[0]), name=str(row[1]), kind="function", detail=str(row[2]))
+            for row in collector.fetch(cur, "functions")
+        ]
+        functions.sort(key=lambda item: (item.schema, item.name, item.detail))
+    return MetadataSnapshot(schemas=schema_names, objects=objects, columns=columns, functions=functions)
+
+
+class _BoundedMetadataCollector:
+    def __init__(self, *, max_rows: int, schemas: Sequence[str]) -> None:
+        self.max_rows = max_rows
+        self.schemas = tuple(schema for schema in schemas if schema)
+        self.collected = 0
+
+    def query(
+        self,
+        base_query: str,
+        schema_column: str,
+        *,
+        extra_predicates: Sequence[str] = (),
+    ) -> tuple[str, tuple[Any, ...]]:
+        predicates = list(extra_predicates)
+        params: list[Any] = []
+        predicates.append(f"{schema_column} NOT LIKE %s")
+        params.append("pg_toast%")
+        if self.schemas:
+            predicates.append(f"{schema_column} = ANY(%s)")
+            params.append(list(self.schemas))
+        remaining = self.max_rows - self.collected + 1
+        return f"{base_query} WHERE {' AND '.join(predicates)} LIMIT %s", (*params, remaining)
+
+    def fetch(self, cursor: Any, label: str) -> list[Any]:
+        remaining = self.max_rows - self.collected
+        rows = list(cursor.fetchmany(remaining + 1))
+        if len(rows) > remaining:
+            schema_hint = ""
+            if self.schemas:
+                schema_hint = f" Current filter: {', '.join(self.schemas)}."
+            raise MetadataLimitExceeded(
+                f"PostgreSQL metadata collection stopped after reaching {self.max_rows} rows while loading {label}."
+                f"{schema_hint} Schema filtering is required: add or narrow metadata_schemas,"
+                " raise metadata_max_rows, or disable metadata."
+            )
+        self.collected += len(rows)
+        return rows
+
+
+def relation_names(snapshot: MetadataSnapshot) -> Iterable[tuple[str, str]]:
+    for item in snapshot.objects:
+        yield item.schema, item.name
+
+
+def _relation_kind(value: str) -> str:
+    return {
+        "r": "table",
+        "p": "table",
+        "v": "view",
+        "m": "view",
+        "f": "foreign table",
+    }.get(value, "relation")

jusi_postgres/runner.py

@@ -0,0 +1,587 @@
+from __future__ import annotations
+
+import json
+import curses
+from pathlib import Path
+import sys
+import tempfile
+import threading
+import uuid
+from collections import deque
+from typing import Any
+
+import visidata
+from visidata import ItemColumn, SequenceSheet, run, vd
+
+from jusi_sql import (
+    MetadataCache,
+    MetadataSnapshot,
+    SqlCompletionRequest,
+    SqlSheetActions,
+    bind_sql_actions,
+    complete_sql,
+    install_visidata_commands,
+    sql_cache_directory,
+)
+
+from .config import DEFAULT_METADATA_MAX_ROWS, kerberos_cache_env, parse_postgres_options
+from .constants import POSTGRES_BOOTSTRAP_SQL
+from .ipc import ApplicationController
+from .metadata import load_postgres_metadata
+
+
+RESULT_QUERY_PREFIXES = ("select", "with", "values", "table")
+POSTGRES_KEYWORDS = (
+    "SELECT", "FROM", "WHERE", "JOIN", "LEFT", "RIGHT", "FULL", "INNER", "OUTER",
+    "ON", "GROUP", "BY", "ORDER", "HAVING", "LIMIT", "OFFSET", "INSERT", "INTO",
+    "VALUES", "UPDATE", "SET", "DELETE", "RETURNING", "WITH", "AS", "DISTINCT",
+    "CREATE", "ALTER", "DROP", "TABLE", "VIEW", "INDEX", "BEGIN", "COMMIT", "ROLLBACK",
+)
+_PENDING_SHEETS: deque[Any] = deque()
+
+
+class RawBinaryValue:
+    __slots__ = ("value",)
+
+    def __init__(self, value: bytes | bytearray | memoryview) -> None:
+        self.value = value
+
+    @property
+    def size(self) -> int:
+        if isinstance(self.value, memoryview):
+            return self.value.nbytes
+        return len(self.value)
+
+    def tobytes(self) -> bytes:
+        if isinstance(self.value, memoryview):
+            return self.value.tobytes()
+        if isinstance(self.value, bytearray):
+            return bytes(self.value)
+        return self.value
+
+    def __str__(self) -> str:
+        return f"<binary data: {self.size} bytes>"
+
+    def __repr__(self) -> str:
+        return str(self)
+
+
+class PostgresSession:
+    def __init__(
+        self,
+        *,
+        alias: str,
+        connect_options: dict[str, Any],
+        krb5ccname: str = "",
+        initial_fetch: int = 100,
+        collect_metadata: bool = True,
+        metadata_max_rows: int = DEFAULT_METADATA_MAX_ROWS,
+        metadata_schemas: tuple[str, ...] = (),
+    ) -> None:
+        self.alias = alias
+        self.connect_options = connect_options
+        self.krb5ccname = krb5ccname
+        self.initial_fetch = initial_fetch
+        self.collect_metadata = collect_metadata
+        self.metadata_max_rows = metadata_max_rows
+        self.metadata_schemas = metadata_schemas
+        self.conn: Any = None
+        self.metadata_conn: Any = None
+        self.metadata_conn_lock = threading.Lock()
+        self.metadata_warning_lock = threading.Lock()
+        self.metadata_warnings: list[str] = []
+        self.lock = threading.RLock()
+        self.notices: list[str] = []
+        self.sheets: list[PostgresResultSheet] = []
+        metadata_cache_options = dict(connect_options)
+        metadata_cache_options["__metadata_max_rows"] = metadata_max_rows
+        metadata_cache_options["__metadata_schemas"] = metadata_schemas
+        self.metadata = MetadataCache(
+            sql_cache_directory("postgres", alias, metadata_cache_options),
+            self._load_metadata,
+            on_warning=self._metadata_warning,
+        )
+
+    def connect(self) -> Any:
+        with self.lock:
+            if self.conn is None or self.conn.closed:
+                with kerberos_cache_env(self.krb5ccname):
+                    self.conn = _connect_psycopg(self.connect_options)
+                self.conn.autocommit = False
+                try:
+                    self.conn.add_notice_handler(self._notice_handler)
+                except Exception:
+                    pass
+            return self.conn
+
+    def with_connection(self, fn, *, blocking: bool = True):  # type: ignore[no-untyped-def]
+        if not self.lock.acquire(blocking=blocking):
+            raise RuntimeError("PostgreSQL connection is busy")
+        try:
+            conn = self.connect()
+            return fn(conn)
+        finally:
+            self.lock.release()
+
+    def register_sheet(self, sheet: "PostgresResultSheet") -> None:
+        self.sheets.append(sheet)
+
+    def complete(self, request: SqlCompletionRequest) -> dict[str, Any]:
+        self.show_metadata_warnings()
+        snapshot = MetadataSnapshot() if not self.collect_metadata else self.metadata.snapshot()
+        return complete_sql(snapshot, request, keywords=POSTGRES_KEYWORDS)
+
+    def enter_cell(self) -> None:
+        if not self.collect_metadata:
+            return
+        self.metadata.ensure_fresh_async()
+
+    def followup(self, body: str) -> None:
+        sql = _followup_sql(body).strip()
+        if not sql:
+            return
+        self.enter_cell()
+        sheet = PostgresResultSheet(session=self, query=sql)
+        _queue_sheet(sheet)
+
+    def interrupt(self) -> None:
+        conn = self.conn
+        if conn is None or conn.closed:
+            return
+        try:
+            conn.cancel()
+            vd.warning("PostgreSQL query cancellation requested")
+        except Exception as exc:
+            vd.warning(f"PostgreSQL cancellation failed: {exc}")
+
+    def commit(self) -> None:
+        conn = self.connect()
+        with self.lock:
+            conn.commit()
+        self._mark_cursors_closed("transaction committed")
+        self.metadata.mark_stale()
+        vd.status("PostgreSQL transaction committed")
+
+    def rollback(self) -> None:
+        conn = self.connect()
+        with self.lock:
+            conn.rollback()
+        self._mark_cursors_closed("transaction rolled back")
+        self.metadata.mark_stale()
+        vd.status("PostgreSQL transaction rolled back")
+
+    def close(self) -> None:
+        metadata_done = self.metadata.close(timeout=2.0)
+        if not metadata_done:
+            self._cancel_metadata()
+        for sheet in list(self.sheets):
+            sheet.close_cursor()
+        conn = self.conn
+        if conn is not None and not conn.closed:
+            conn.close()
+
+    def _load_metadata(self) -> Any:
+        with kerberos_cache_env(self.krb5ccname):
+            conn = _connect_psycopg(dict(self.connect_options))
+        with self.metadata_conn_lock:
+            self.metadata_conn = conn
+        try:
+            try:
+                conn.autocommit = True
+            except Exception:
+                pass
+            return load_postgres_metadata(
+                conn,
+                max_rows=self.metadata_max_rows,
+                schemas=self.metadata_schemas,
+            )
+        finally:
+            with self.metadata_conn_lock:
+                self.metadata_conn = None
+            try:
+                conn.close()
+            except Exception:
+                pass
+
+    def _cancel_metadata(self) -> None:
+        with self.metadata_conn_lock:
+            conn = self.metadata_conn
+        if conn is None or conn.closed:
+            return
+        try:
+            conn.cancel()
+            vd.warning("PostgreSQL metadata collection cancellation requested")
+        except Exception as exc:
+            vd.warning(f"PostgreSQL metadata cancellation failed: {exc}")
+
+    def _metadata_warning(self, message: str) -> None:
+        with self.metadata_warning_lock:
+            self.metadata_warnings.append(message)
+
+    def show_metadata_warnings(self) -> None:
+        with self.metadata_warning_lock:
+            warnings = list(self.metadata_warnings)
+            self.metadata_warnings.clear()
+        for message in warnings:
+            vd.warning(message)
+
+    def pop_notices(self) -> list[str]:
+        notices = list(self.notices)
+        self.notices.clear()
+        return notices
+
+    def _notice_handler(self, diagnostic: Any) -> None:
+        message = str(getattr(diagnostic, "message_primary", "") or diagnostic).strip()
+        if message:
+            self.notices.append(message)
+
+    def _mark_cursors_closed(self, reason: str) -> None:
+        for sheet in self.sheets:
+            sheet.cursor_closed_reason = reason
+
+
+class PostgresResultSheet(SequenceSheet):
+    rowtype = "rows"
+
+    def __init__(self, *, session: PostgresSession, query: str) -> None:
+        super().__init__(name=session.alias, source=query)
+        self.session = session
+        self.query = query
+        self.cursor_name = f"jusi_pg_{uuid.uuid4().hex}"
+        self.cursor: Any = None
+        self.exhausted = False
+        self.cursor_closed_reason = ""
+        self._buffer: list[Any] = []
+        session.register_sheet(self)
+        bind_sql_actions(self, SqlSheetActions(
+            fetch_more=self.fetch_more,
+            commit=session.commit,
+            rollback=session.rollback,
+        ))
+
+    def iterload(self):  # type: ignore[no-untyped-def]
+        try:
+            if _looks_like_result_query(self.query):
+                yield from self._load_result_query()
+            else:
+                yield from self._load_statement()
+        except Exception as exc:
+            vd.exceptionCaught(exc)
+            vd.warning(f"PostgreSQL query failed: {exc.__class__.__name__}: {exc}; press Ctrl-E for details")
+
+    def fetch_more(self, count: int) -> int:
+        if self.cursor_closed_reason:
+            vd.warning(f"PostgreSQL cursor is closed: {self.cursor_closed_reason}")
+            return 0
+        if self.exhausted or self.cursor is None:
+            vd.status("PostgreSQL cursor is exhausted")
+            return 0
+        try:
+            with self.session.lock:
+                rows = self._fetch_rows(count)
+            for row in rows:
+                self.addRow(_display_row(row))
+            self._notify_more()
+            return len(rows)
+        except Exception as exc:
+            vd.warning(f"PostgreSQL fetch failed: {exc}")
+            return 0
+
+    def close_cursor(self) -> None:
+        cursor = self.cursor
+        self.cursor = None
+        if cursor is None:
+            return
+        try:
+            cursor.close()
+        except Exception:
+            pass
+
+    def _load_result_query(self):  # type: ignore[no-untyped-def]
+        conn = self.session.connect()
+        with self.session.lock:
+            self.cursor = conn.cursor(name=self.cursor_name)
+            self.cursor.execute(self.query)
+            description = self.cursor.description or []
+            column_names = [str(item.name) for item in description] if description else ["result"]
+            self.columns = [ItemColumn(name, index) for index, name in enumerate(column_names)]
+            rows = self._fetch_rows(self.session.initial_fetch)
+        if description:
+            yield column_names
+        for row in rows:
+            yield _display_row(row)
+        for notice in self.session.pop_notices():
+            vd.status(f"PostgreSQL notice: {notice}")
+        self.session.show_metadata_warnings()
+        self._notify_more()
+
+    def _load_statement(self):  # type: ignore[no-untyped-def]
+        conn = self.session.connect()
+        with self.session.lock:
+            with conn.cursor() as cursor:
+                cursor.execute(self.query)
+                description = cursor.description or []
+                if description:
+                    column_names = [str(item.name) for item in description]
+                    self.columns = [ItemColumn(name, index) for index, name in enumerate(column_names)]
+                    rows = cursor.fetchall()
+                    yield column_names
+                    for row in rows:
+                        yield _display_row(row)
+                else:
+                    self.columns = [ItemColumn("status", 0), ItemColumn("value", 1)]
+                    status = str(getattr(cursor, "statusmessage", "") or "done")
+                    yield ["status", status]
+                    rowcount = int(getattr(cursor, "rowcount", -1) or -1)
+                    if rowcount >= 0:
+                        yield ["rowcount", rowcount]
+                    for notice in self.session.pop_notices():
+                        yield ["notice", notice]
+                    self.session.metadata.mark_stale()
+        self.session.show_metadata_warnings()
+
+    def _fetch_rows(self, count: int) -> list[Any]:
+        if self.cursor is None:
+            return []
+        if count == 0:
+            rows = list(self._buffer)
+            self._buffer.clear()
+            rows.extend(self.cursor.fetchall())
+            self.exhausted = True
+            return rows
+        rows = list(self._buffer[:count])
+        self._buffer = self._buffer[count:]
+        remaining = count - len(rows)
+        if remaining > 0:
+            fetched = list(self.cursor.fetchmany(remaining + 1))
+            rows.extend(fetched[:remaining])
+            if len(fetched) > remaining:
+                self._buffer.append(fetched[-1])
+            else:
+                self.exhausted = True
+        return rows
+
+    def _notify_more(self) -> None:
+        if self._buffer or not self.exhausted:
+            vd.warning("PostgreSQL cursor has more rows; press 1-9 or gf to fetch more")
+        else:
+            vd.status("PostgreSQL cursor exhausted")
+
+
+def install_postgres_commands() -> None:
+    install_visidata_commands(visidata)
+    if getattr(visidata.BaseSheet, "_jusi_postgres_commands_v1", False):
+        return
+
+    @visidata.BaseSheet.command("gb", "jusi-postgres-open-raw-value", "open raw PostgreSQL cell value", replay=False)
+    def _open_raw_value(sheet: Any) -> None:
+        value = getattr(sheet, "cursorValue", None)
+        if callable(value):
+            value = value()
+        value = value if value is not None else ""
+        extension = str(vd.input("extension: ") or "").strip().lstrip(".")
+        suffix = f".{extension}" if extension else ""
+        path = _write_raw_value_file(value, suffix)
+        opened = vd.openPath(visidata.Path(path))
+        vd.push(opened)
+
+    @visidata.BaseSheet.command("", "jusi-postgres-open-pending-sheet", "open pending PostgreSQL result", replay=False)
+    def _open_pending(_sheet: Any) -> None:
+        if not _PENDING_SHEETS:
+            return
+        next_sheet = _PENDING_SHEETS.popleft()
+        vd.push(next_sheet)
+        next_sheet.ensureLoaded()
+
+    setattr(visidata.BaseSheet, "_jusi_postgres_commands_v1", True)
+
+
+def _queue_sheet(sheet: PostgresResultSheet) -> None:
+    _PENDING_SHEETS.append(sheet)
+    vd.queueCommand("jusi-postgres-open-pending-sheet")
+    try:
+        curses.ungetch(curses.KEY_RESIZE)
+    except Exception:
+        pass
+
+
+def _followup_sql(body: str) -> str:
+    first, separator, remainder = body.partition("\n")
+    header = first.strip()
+    if header == "%%sql" or header.startswith(("%%sql ", "%%sql\t")):
+        return remainder if separator else ""
+    return body
+
+
+def _postgres_sheet(sheet: Any) -> PostgresResultSheet | None:
+    current = sheet
+    seen: set[int] = set()
+    while current is not None:
+        marker = id(current)
+        if marker in seen:
+            break
+        seen.add(marker)
+        if isinstance(current, PostgresResultSheet):
+            return current
+        current = getattr(current, "source", None)
+    vd.warning("No active PostgreSQL result sheet")
+    return None
+
+
+def _write_raw_value_file(value: Any, suffix: str) -> str:
+    if isinstance(value, RawBinaryValue):
+        value = value.tobytes()
+    if isinstance(value, memoryview):
+        value = value.tobytes()
+    if isinstance(value, bytearray):
+        value = bytes(value)
+    if isinstance(value, bytes):
+        with tempfile.NamedTemporaryFile("wb", prefix="jusi-postgres-value-", suffix=suffix, delete=False) as handle:
+            handle.write(value)
+            return handle.name
+    with tempfile.NamedTemporaryFile("w", encoding="utf-8", prefix="jusi-postgres-value-", suffix=suffix, delete=False) as handle:
+        handle.write(_value_to_text(value))
+        return handle.name
+
+
+def _value_to_text(value: Any) -> str:
+    if isinstance(value, (dict, list, tuple)):
+        return json.dumps(value, ensure_ascii=False, default=str, indent=2)
+    return "" if value is None else str(value)
+
+
+def _display_row(row: Any) -> list[Any]:
+    return [_display_cell(value) for value in row]
+
+
+def _display_cell(value: Any) -> Any:
+    if isinstance(value, RawBinaryValue):
+        return value
+    if isinstance(value, (bytes, bytearray, memoryview)):
+        return RawBinaryValue(value)
+    return value
+
+
+def _looks_like_result_query(sql: str) -> bool:
+    stripped = sql.lstrip().lower()
+    return stripped.startswith(RESULT_QUERY_PREFIXES)
+
+
+def _connect_psycopg(connect_options: dict[str, Any]) -> Any:
+    try:
+        import psycopg
+    except ModuleNotFoundError as exc:
+        raise RuntimeError(
+            "Missing dependency 'psycopg'. Install this plugin with dependencies, "
+            "for example: ./.venv/bin/python -m pip install -e ."
+        ) from exc
+    conn = psycopg.connect(**connect_options)
+    _install_infinity_timestamp_loaders(conn)
+    return conn
+
+
+def _install_infinity_timestamp_loaders(conn: Any) -> None:
+    try:
+        from psycopg.types.datetime import DateLoader, TimestampLoader, TimestamptzLoader
+    except Exception:
+        return
+
+    class DateInfinityLoader(DateLoader):  # type: ignore[misc, valid-type]
+        def load(self, data: Any) -> Any:
+            text = bytes(data).decode("ascii")
+            if text in ("infinity", "-infinity"):
+                return text
+            return super().load(data)
+
+    class TimestampInfinityLoader(TimestampLoader):  # type: ignore[misc, valid-type]
+        def load(self, data: Any) -> Any:
+            text = bytes(data).decode("ascii")
+            if text in ("infinity", "-infinity"):
+                return text
+            return super().load(data)
+
+    class TimestamptzInfinityLoader(TimestamptzLoader):  # type: ignore[misc, valid-type]
+        def load(self, data: Any) -> Any:
+            text = bytes(data).decode("ascii")
+            if text in ("infinity", "-infinity"):
+                return text
+            return super().load(data)
+
+    conn.adapters.register_loader("date", DateInfinityLoader)
+    conn.adapters.register_loader("timestamp", TimestampInfinityLoader)
+    conn.adapters.register_loader("timestamptz", TimestamptzInfinityLoader)
+
+
+def _read_payload(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    finally:
+        path.unlink(missing_ok=True)
+    if not isinstance(value, dict):
+        raise RuntimeError("invalid PostgreSQL application payload")
+    return value
+
+
+def _handle_application_operation(session: PostgresSession, operation: str, payload: dict[str, Any]) -> dict[str, Any]:
+    if operation == "followup":
+        body = payload.get("body")
+        if not isinstance(body, str):
+            raise ValueError("SQL followup requires string body")
+        session.followup(body)
+        return {"accepted": True}
+    if operation == "complete":
+        return session.complete(SqlCompletionRequest.from_payload(payload))
+    if operation == "interrupt":
+        session.interrupt()
+        return {"accepted": True}
+    raise ValueError(f"unsupported PostgreSQL application operation: {operation}")
+
+
+def run_postgres_application(payload_path: Path, socket_path: str) -> int:
+    session: PostgresSession | None = None
+    try:
+        from jusi.plugins.vd.application import install_editor_actions
+
+        install_postgres_commands()
+        install_editor_actions()
+        visidata.vd.timeouts_before_idle = -1
+        payload = _read_payload(payload_path)
+        query = str(payload.get("sql", "")).strip() or POSTGRES_BOOTSTRAP_SQL
+        alias = str(payload.get("alias", "")).strip()
+        if not alias:
+            raise RuntimeError("missing SQL target alias")
+        raw_options = payload.get("options")
+        if not isinstance(raw_options, dict):
+            raise RuntimeError("missing PostgreSQL target options")
+        options = parse_postgres_options(raw_options)
+        session = PostgresSession(
+            alias=alias,
+            connect_options=options.connect,
+            krb5ccname=options.krb5ccname,
+            initial_fetch=options.initial_fetch,
+            collect_metadata=options.collect_metadata,
+            metadata_max_rows=options.metadata_max_rows,
+            metadata_schemas=options.metadata_schemas,
+        )
+        controller = ApplicationController(
+            socket_path,
+            lambda operation, control_payload: _handle_application_operation(session, operation, control_payload),
+        )
+        controller.start()
+        session.enter_cell()
+        sheet = PostgresResultSheet(session=session, query=query)
+        run(sheet)
+        return 0
+    except Exception as exc:
+        sys.stderr.write(str(exc) + "\n")
+        sys.stderr.flush()
+        return 2
+    finally:
+        if session is not None:
+            session.close()
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 4 or sys.argv[1] != "--application":
+        raise SystemExit("PostgreSQL application requires a private payload path and control socket")
+    raise SystemExit(run_postgres_application(Path(sys.argv[2]), sys.argv[3]))

jusi_postgres/worker.py

@@ -0,0 +1,108 @@
+"""Jusi 1.0 worker boundary; imports neither IPython nor VisiData."""
+from __future__ import annotations
+
+from importlib.util import find_spec
+import os
+from pathlib import Path
+import sys
+import tempfile
+from typing import Any
+
+from jusi.plugin_api import OperationRejected, WorkerResult, copy_text, open_text, show_diff, terminal_surface
+from jusi_sql import SqlCompletionRequest
+from jusi_sql.worker import SqlExecuteRequest, SqlWorker, StagedApplicationPayload
+
+from .ipc import WorkerApplicationBridge
+
+
+class PostgresClientSession:
+    def __init__(self, context: object) -> None:
+        self.context = context
+        self.runtime_directory: Path | None = None
+        self.payload: StagedApplicationPayload | None = None
+        self.bridge: WorkerApplicationBridge | None = None
+
+    def execute(self, request: SqlExecuteRequest) -> WorkerResult:
+        if self.runtime_directory is not None:
+            raise OperationRejected("PostgreSQL client is already initialized", reason="conflict")
+        if find_spec("visidata") is None:
+            raise OperationRejected("%%sql requires VisiData; install jusi-postgres with dependencies", reason="unsupported")
+        self.runtime_directory = Path(tempfile.mkdtemp(prefix="jusi-postgres-", dir="/tmp"))
+        self.runtime_directory.chmod(0o700)
+        socket_path = str(self.runtime_directory / "control.sock")
+        try:
+            self.payload = StagedApplicationPayload(
+                {"alias": request.alias, "sql": request.sql, "options": request.options},
+                prefix="jusi-postgres-payload-",
+            )
+            self.bridge = WorkerApplicationBridge(socket_path)
+            return WorkerResult(
+                {"accepted": True, "alias": request.alias},
+                (terminal_surface(
+                    "postgres_visidata",
+                    (sys.executable, "-m", "jusi_postgres.runner", "--application", str(self.payload.path), socket_path),
+                    environment_overrides={"TERM": os.environ.get("JUSI_SQL_TERM", "").strip() or "xterm-256color"},
+                    signal=True,
+                ),),
+            )
+        except BaseException:
+            self.close()
+            raise
+
+    def followup(self, body: str) -> dict[str, Any]:
+        return self._request("followup", {"body": body})
+
+    def complete(self, request: SqlCompletionRequest) -> dict[str, Any]:
+        return self._request("complete", {
+            "body": request.body,
+            "prefix": request.prefix,
+            "cursor_pos": request.cursor_pos,
+            "cursor_row": request.cursor_row,
+            "cursor_col": request.cursor_col,
+        })
+
+    def interrupt(self) -> None:
+        if self.bridge is not None:
+            self.bridge.interrupt()
+
+    def editor_action(self, action: str, selection: dict[str, Any]) -> WorkerResult:
+        if action == "show_diff":
+            before, after = selection.get("before"), selection.get("after")
+            if not isinstance(before, str) or not isinstance(after, str):
+                raise OperationRejected("PostgreSQL diff selection requires before and after text", reason="invalid_request")
+            return show_diff(before, after, filetype="sql")
+        text = selection.get("text")
+        if not isinstance(text, str):
+            raise OperationRejected("PostgreSQL selection requires text", reason="invalid_request")
+        if action == "copy":
+            return copy_text(text, linewise=bool(selection.get("linewise", False)))
+        if action == "open":
+            return open_text(text, name="selection.sql", filetype="sql")
+        raise OperationRejected(f"Unsupported PostgreSQL editor action: {action}", reason="unsupported")
+
+    def _request(self, operation: str, payload: dict[str, Any]) -> dict[str, Any]:
+        if self.bridge is None:
+            raise OperationRejected("PostgreSQL client is not initialized", reason="conflict")
+        response = self.bridge.request(operation, payload)
+        if response.get("ok") is not True:
+            raise RuntimeError(str(response.get("message", "PostgreSQL terminal application failed")))
+        result = response.get("result", {})
+        return dict(result) if isinstance(result, dict) else {"accepted": True}
+
+    def close(self) -> None:
+        if self.bridge is not None:
+            self.bridge.close()
+            self.bridge = None
+        if self.payload is not None:
+            self.payload.close()
+            self.payload = None
+        if self.runtime_directory is not None:
+            try:
+                self.runtime_directory.rmdir()
+            except OSError:
+                pass
+            self.runtime_directory = None
+
+
+def create_worker(context: object) -> SqlWorker:
+    return SqlWorker(context, PostgresClientSession)

jusi_postgres-0.2.0.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: jusi-postgres
+Version: 0.2.0
+Summary: PostgreSQL provider plugin for Jusi SQL
+Author: Jusi contributors
+License: MIT License
+        
+        Copyright (c) 2026 notawhaleble
+        
+        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.
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: jusi-sql<0.3,>=0.2
+Requires-Dist: jusi<2,>=1.0
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: visidata<4,>=3
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# jusi-postgres
+
+`jusi-postgres` is the PostgreSQL exact-provider plugin for Jusi 1.0 and the
+shared `jusi-sql` family. It exposes the `postgres`/`postgresql` provider for
+`%%sql` cells. The family owns target selection, magic dispatch, completion
+ranges, metadata caching, operation routing, and common VisiData SQL commands.
+
+Example session config:
+
+```toml
+[sql.targets.analytics]
+provider = "postgres"
+host = "localhost"
+port = 5432
+dbname = "analytics"
+user = "me"
+initial_fetch = 100
+```
+
+All psycopg connection options may be provided in the target config. The
+additional `krb5ccname` option points at a custom Kerberos credential cache and
+is passed to libpq through `KRB5CCNAME` while connecting.
+
+Metadata for SQL completion is collected asynchronously on a separate
+connection. Large catalogs should be filtered or disabled:
+
+```toml
+[sql.targets.analytics]
+provider = "postgres"
+host = "db.example.com"
+dbname = "analytics"
+user = "me"
+metadata_schemas = ["public", "analytics"]
+metadata_max_rows = 1000000
+collect_metadata = true
+```
+
+Use `collect_metadata = false` to skip completion metadata for a target. If
+collection crosses `metadata_max_rows`, it stops and warns that schema
+filtering is required. Provider options belong in the target configuration;
+the shared Jusi 1.0 `%%sql` syntax accepts one target alias.
+
+VisiData mappings:
+
+- `1` to `9`: fetch that many more rows for the active result sheet.
+- `gf`: prompt for a row count to fetch; `0` fetches the rest of the cursor.
+- `gc`: commit the current connection.
+- `gr`: roll back the current connection.
+- `gb`: write the selected raw cell value to a temporary file and open it with
+  VisiData. The command prompts for an optional extension; an empty extension
+  lets VisiData infer the file type from content and filename.
+
+Follow-up cells reuse the same VisiData application, PostgreSQL connection,
+transaction, and server-side cursors. `JusiInterrupt` requests cancellation on
+that connection. Closing the client closes its cursors, metadata connection,
+main connection, private control socket, and staged launch data.
+
+## Local development database
+
+Start a disposable PostgreSQL fixture:
+
+```sh
+scripts/run-postgres.sh
+```
+
+The script builds `jusi-postgres-dev`, runs a local container on
+`127.0.0.1:55432`, waits for readiness, and prints this config:
+
+```toml
+[sql.targets.local_postgres]
+provider = "postgres"
+host = "127.0.0.1"
+port = 55432
+dbname = "jusi"
+user = "jusi"
+password = "jusi"
+initial_fetch = 25
+```
+
+The fixture creates `demo.accounts`, `demo.events`, `demo.account_summary`,
+`demo.account_event_count(bigint)`, and `demo.blob_files` for result browsing,
+completion checks, and raw bytea/blob handling.
+
+For an already-running development container, install or refresh the blob table:
+
+```sh
+scripts/install-blob-fixture.sh
+```
+
+The source zip fixture is stored at `fixtures/test-blob.zip`.

jusi_postgres-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+jusi_postgres/__init__.py,sha256=d6scTnvCGaeWi2znFmWZdJWIT_RDs_YpJgju1AmgQhU,85
+jusi_postgres/catalog.py,sha256=7UA_Ya4BGiQDMpQNTxOIVeQalK0ZOPr4NW9kO4ZKqR0,567
+jusi_postgres/config.py,sha256=K4PpoHtTiFlCOSSMlYTO0y64WVIDkMJ2iITLGQq9F1k,3132
+jusi_postgres/constants.py,sha256=mTKICXjO4sCCnxJybDj0MQMpp7Ajw_WDG4toRn8iBME,102
+jusi_postgres/ipc.py,sha256=ZJPFKXJkeJujnW7p_l9HSz4WLboOgllOjE_WJTuXMhk,5217
+jusi_postgres/kernel.py,sha256=W2XwL_ERzCtz0ACYK5NO4vmxlrfzZO_XfWN0Fg5smO0,532
+jusi_postgres/metadata.py,sha256=mxC_1bCfeht67doIlzDMzMgy3qIVHL1qqF2zqtPNms0,4437
+jusi_postgres/runner.py,sha256=At60_N-Ipk-MUVB-M03adun_oNHfrCYoqf95VFpY2EQ,21073
+jusi_postgres/worker.py,sha256=vrfj1QZWKGd9noVqUpfIQcbOIVaiy41M6Vf5oHB4A5g,4789
+jusi_postgres-0.2.0.dist-info/METADATA,sha256=vVg230lQZ38jyDHz6hq0Z-7ft1voSPXCDN6g_tSwYKI,4540
+jusi_postgres-0.2.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+jusi_postgres-0.2.0.dist-info/entry_points.txt,sha256=tonMp8WiCpv5BzuJKQZ9H82uPwhTVejvYA-4I90bmuE,65
+jusi_postgres-0.2.0.dist-info/licenses/LICENSE,sha256=YSDMzYJrAu4QMyHcnOSrhmjYzkD9rEKha8G2CH4p3AA,1069
+jusi_postgres-0.2.0.dist-info/RECORD,,

jusi_postgres-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

jusi_postgres-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[jusi.plugins.v1]
+postgres = jusi_postgres.catalog:catalog_entry

jusi_postgres-0.2.0.dist-info/licenses/LICENSE

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