jusi-postgres 0.2.0__tar.gz

jusi_postgres-0.2.0/.gitignore

@@ -0,0 +1,25 @@
+.DS_Store
+
+# Local Python environments
+.venv/
+venv/
+env/
+
+# Python bytecode and test caches
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+pytest-of-*/
+
+# Packaging/build outputs
+*.egg-info/
+build/
+dist/
+
+# Local runtime scratch
+.tmp/
+*.log

jusi_postgres-0.2.0/Dockerfile

@@ -0,0 +1,6 @@
+FROM postgres:16-alpine
+
+LABEL org.opencontainers.image.title="jusi-postgres-dev"
+LABEL org.opencontainers.image.description="Local PostgreSQL fixture for jusi-postgres development"
+
+COPY docker/postgres/initdb.d/ /docker-entrypoint-initdb.d/

jusi_postgres-0.2.0/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.

jusi_postgres-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,90 @@
+# 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/docker/postgres/initdb.d/001_jusi_demo.sql

@@ -0,0 +1,52 @@
+CREATE SCHEMA IF NOT EXISTS demo;
+
+CREATE TABLE IF NOT EXISTS demo.accounts (
+    id bigserial PRIMARY KEY,
+    email text NOT NULL UNIQUE,
+    display_name text NOT NULL,
+    active boolean NOT NULL DEFAULT true,
+    created_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS demo.events (
+    id bigserial PRIMARY KEY,
+    account_id bigint NOT NULL REFERENCES demo.accounts(id),
+    event_type text NOT NULL,
+    payload jsonb NOT NULL DEFAULT '{}'::jsonb,
+    created_at timestamptz NOT NULL DEFAULT now()
+);
+
+INSERT INTO demo.accounts (email, display_name, active)
+VALUES
+    ('ada@example.test', 'Ada Lovelace', true),
+    ('grace@example.test', 'Grace Hopper', true),
+    ('alan@example.test', 'Alan Turing', false)
+ON CONFLICT (email) DO NOTHING;
+
+INSERT INTO demo.events (account_id, event_type, payload)
+SELECT account_id, event_type, payload::jsonb
+FROM (
+    VALUES
+        (1, 'login', '{"ip": "127.0.0.1"}'),
+        (1, 'query', '{"rows": 42}'),
+        (2, 'login', '{"ip": "127.0.0.2"}'),
+        (3, 'disabled_login', '{"reason": "inactive"}')
+) AS seed(account_id, event_type, payload)
+WHERE NOT EXISTS (SELECT 1 FROM demo.events);
+
+CREATE OR REPLACE FUNCTION demo.account_event_count(account_id bigint)
+RETURNS bigint
+LANGUAGE sql
+STABLE
+AS $$
+    SELECT count(*) FROM demo.events e WHERE e.account_id = $1
+$$;
+
+CREATE OR REPLACE VIEW demo.account_summary AS
+SELECT
+    a.id,
+    a.email,
+    a.display_name,
+    a.active,
+    demo.account_event_count(a.id) AS event_count
+FROM demo.accounts a;

jusi_postgres-0.2.0/docker/postgres/initdb.d/002_jusi_blob_fixture.sql

@@ -0,0 +1,20 @@
+CREATE TABLE IF NOT EXISTS demo.blob_files (
+    id bigserial PRIMARY KEY,
+    filename text NOT NULL UNIQUE,
+    content_type text NOT NULL,
+    payload bytea NOT NULL,
+    created_at timestamptz NOT NULL DEFAULT now()
+);
+
+INSERT INTO demo.blob_files (filename, content_type, payload)
+VALUES (
+    'test-blob.zip',
+    'application/zip',
+    decode(
+        '504b03040a0000000000231ab65c2909ab311b0000001b0000000f001c00626c6f622d726561646d652e747874555409000382a00f6a82a00f6a75780b000104f501000004140000004a75736920506f73746772657320626c6f6220666978747572650a504b01021e030a0000000000231ab65c2909ab311b0000001b0000000f0018000000000001000000a48100000000626c6f622d726561646d652e747874555405000382a00f6a75780b000104f50100000414000000504b0506000000000100010055000000640000000000',
+        'hex'
+    )
+)
+ON CONFLICT (filename) DO UPDATE
+SET content_type = EXCLUDED.content_type,
+    payload = EXCLUDED.payload;

jusi_postgres-0.2.0/examples/jusi.toml

@@ -0,0 +1,8 @@
+[sql.targets.local_postgres]
+provider = "postgres"
+host = "127.0.0.1"
+port = 55432
+dbname = "jusi"
+user = "jusi"
+password = "jusi"
+initial_fetch = 25

jusi_postgres-0.2.0/fixtures/blob-readme.txt

@@ -0,0 +1 @@
+Jusi Postgres blob fixture

jusi_postgres-0.2.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "jusi-postgres"
+version = "0.2.0"
+description = "PostgreSQL provider plugin for Jusi SQL"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Jusi contributors" }
+]
+dependencies = [
+  "jusi>=1.0,<2",
+  "jusi-sql>=0.2,<0.3",
+  "psycopg[binary]>=3.1",
+  "visidata>=3,<4",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8,<9"]
+
+[project.entry-points."jusi.plugins.v1"]
+postgres = "jusi_postgres.catalog:catalog_entry"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/jusi_postgres"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

jusi_postgres-0.2.0/scripts/install-blob-fixture.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+CONTAINER_NAME="${JUSI_POSTGRES_CONTAINER:-jusi-postgres-dev}"
+POSTGRES_USER="${JUSI_POSTGRES_USER:-jusi}"
+POSTGRES_DB="${JUSI_POSTGRES_DB:-jusi}"
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SQL_PATH="${ROOT_DIR}/docker/postgres/initdb.d/002_jusi_blob_fixture.sql"
+
+docker exec -i "${CONTAINER_NAME}" psql -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" < "${SQL_PATH}"
+
+cat <<'EOF'
+Blob fixture installed.
+
+Try:
+
+%%sql local_postgres
+select id, filename, content_type, payload
+from demo.blob_files;
+EOF

jusi_postgres-0.2.0/scripts/run-postgres.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+IMAGE_NAME="${JUSI_POSTGRES_IMAGE:-jusi-postgres-dev}"
+CONTAINER_NAME="${JUSI_POSTGRES_CONTAINER:-jusi-postgres-dev}"
+HOST_PORT="${JUSI_POSTGRES_PORT:-55432}"
+POSTGRES_USER="${JUSI_POSTGRES_USER:-jusi}"
+POSTGRES_PASSWORD="${JUSI_POSTGRES_PASSWORD:-jusi}"
+POSTGRES_DB="${JUSI_POSTGRES_DB:-jusi}"
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+docker build -t "${IMAGE_NAME}" "${ROOT_DIR}"
+
+if docker ps --format '{{.Names}}' | grep -Fxq "${CONTAINER_NAME}"; then
+  echo "PostgreSQL container '${CONTAINER_NAME}' is already running on port ${HOST_PORT}."
+else
+  if docker ps -a --format '{{.Names}}' | grep -Fxq "${CONTAINER_NAME}"; then
+    docker rm "${CONTAINER_NAME}" >/dev/null
+  fi
+
+  docker run \
+    --detach \
+    --name "${CONTAINER_NAME}" \
+    --publish "127.0.0.1:${HOST_PORT}:5432" \
+    --env "POSTGRES_USER=${POSTGRES_USER}" \
+    --env "POSTGRES_PASSWORD=${POSTGRES_PASSWORD}" \
+    --env "POSTGRES_DB=${POSTGRES_DB}" \
+    "${IMAGE_NAME}" >/dev/null
+fi
+
+echo "Waiting for PostgreSQL to accept connections..."
+for _ in $(seq 1 60); do
+  if docker exec "${CONTAINER_NAME}" pg_isready -U "${POSTGRES_USER}" -d "${POSTGRES_DB}" >/dev/null 2>&1; then
+    cat <<EOF
+PostgreSQL is running.
+
+jusi.toml:
+
+[sql.targets.local_postgres]
+provider = "postgres"
+host = "127.0.0.1"
+port = ${HOST_PORT}
+dbname = "${POSTGRES_DB}"
+user = "${POSTGRES_USER}"
+password = "${POSTGRES_PASSWORD}"
+initial_fetch = 25
+EOF
+    exit 0
+  fi
+  sleep 1
+done
+
+echo "PostgreSQL did not become ready in time." >&2
+docker logs "${CONTAINER_NAME}" >&2 || true
+exit 1

jusi_postgres-0.2.0/src/jusi_postgres/__init__.py

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

jusi_postgres-0.2.0/src/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-0.2.0/src/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-0.2.0/src/jusi_postgres/constants.py

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