postgres-aiops 0.1.0__py3-none-any.whl

postgres_aiops/cli/server.py

@@ -0,0 +1,69 @@
+"""``postgres-aiops server`` — server-level reads."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from postgres_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+server_app = typer.Typer(
+    name="server",
+    help="Server reads: version, settings, extensions, databases, roles.",
+    no_args_is_help=True,
+)
+
+
+@server_app.command("version")
+@cli_errors
+def server_version(target: TargetOption = None) -> None:
+    """Server version, uptime and recovery state."""
+    from postgres_aiops.ops import server as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.server_version(conn)))
+
+
+@server_app.command("settings")
+@cli_errors
+def server_settings(
+    pattern: Annotated[str | None, typer.Argument(help="Name substring filter")] = None,
+    target: TargetOption = None,
+) -> None:
+    """Configuration parameters (pg_settings), optionally filtered by name."""
+    from postgres_aiops.ops import server as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.show_settings(conn, pattern)))
+
+
+@server_app.command("extensions")
+@cli_errors
+def server_extensions(target: TargetOption = None) -> None:
+    """Installed extensions."""
+    from postgres_aiops.ops import server as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.list_extensions(conn)))
+
+
+@server_app.command("databases")
+@cli_errors
+def server_databases(target: TargetOption = None) -> None:
+    """Databases with owner, encoding and size."""
+    from postgres_aiops.ops import server as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.list_databases(conn)))
+
+
+@server_app.command("roles")
+@cli_errors
+def server_roles(target: TargetOption = None) -> None:
+    """Roles and their attributes."""
+    from postgres_aiops.ops import server as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.list_roles(conn)))

postgres_aiops/cli/table.py

@@ -0,0 +1,45 @@
+"""``postgres-aiops table`` — table-health reads."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from postgres_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+table_app = typer.Typer(
+    name="table",
+    help="Table health: sizes, bloat, autovacuum.",
+    no_args_is_help=True,
+)
+
+
+@table_app.command("sizes")
+@cli_errors
+def table_sizes(target: TargetOption = None) -> None:
+    """Largest tables by total relation size."""
+    from postgres_aiops.ops import tables as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.table_sizes(conn)))
+
+
+@table_app.command("bloat")
+@cli_errors
+def table_bloat(target: TargetOption = None) -> None:
+    """Dead-tuple bloat proxy per table."""
+    from postgres_aiops.ops import tables as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.table_bloat(conn)))
+
+
+@table_app.command("autovacuum")
+@cli_errors
+def table_autovacuum(target: TargetOption = None) -> None:
+    """Per-table dead tuples and last (auto)vacuum times."""
+    from postgres_aiops.ops import tables as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.autovacuum_status(conn)))

postgres_aiops/config.py

@@ -0,0 +1,154 @@
+"""Configuration management for Postgres AIops.
+
+Loads connection targets from a YAML config file. The secret (the PostgreSQL
+role **password**) is NEVER stored in the config file and never on disk in
+plaintext: it lives in the encrypted store ``~/.postgres-aiops/secrets.enc``
+(see :mod:`postgres_aiops.secretstore`). For backward compatibility a legacy
+plaintext env var (``PG_<TARGET>_PASSWORD``) is still honoured as a fallback,
+with a warning nudging migration to the encrypted store.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+import yaml
+
+from postgres_aiops.secretstore import SecretStoreError, get_secret, has_store
+
+CONFIG_DIR = Path.home() / ".postgres-aiops"
+CONFIG_FILE = CONFIG_DIR / "config.yaml"
+ENV_FILE = CONFIG_DIR / ".env"
+
+DEFAULT_PORT = 5432
+DEFAULT_DBNAME = "postgres"
+DEFAULT_USER = "postgres"
+DEFAULT_SSLMODE = "prefer"
+APPLICATION_NAME = "postgres-aiops"
+
+# Legacy env-var prefix/suffix; also used by the migration helper.
+SECRET_ENV_PREFIX = "PG_"  # nosec B105 — env-var name, not a secret
+SECRET_ENV_SUFFIX = "_PASSWORD"  # nosec B105 — env-var name, not a secret
+
+_log = logging.getLogger("postgres-aiops.config")
+
+
+def _secret_env_key(name: str) -> str:
+    """Legacy per-target password env var name, e.g. PG_PRIMARY_PASSWORD."""
+    return f"{SECRET_ENV_PREFIX}{name.upper().replace('-', '_')}{SECRET_ENV_SUFFIX}"
+
+
+def _resolve_secret(name: str) -> str:
+    """Return a target's password: encrypted store first, then legacy env var."""
+    if has_store():
+        try:
+            return get_secret(name)
+        except SecretStoreError:
+            pass  # fall through to legacy env var
+    legacy = os.environ.get(_secret_env_key(name))
+    if legacy:
+        _log.warning(
+            "Using plaintext env var %s. Migrate to the encrypted store with "
+            "'postgres-aiops secret migrate'.",
+            _secret_env_key(name),
+        )
+        return legacy
+    raise OSError(
+        f"No password for target '{name}'. Add one with "
+        f"'postgres-aiops secret set {name}' (stored encrypted), or run "
+        f"'postgres-aiops init'."
+    )
+
+
+@dataclass(frozen=True)
+class TargetConfig:
+    """A connection target for a PostgreSQL server/cluster.
+
+    The password is sourced from the encrypted secret store (see ``password``),
+    never the config file. ``host``/``port`` locate the server; ``dbname`` is the
+    database to connect to; ``sslmode`` follows libpq semantics
+    (disable/allow/prefer/require/verify-ca/verify-full).
+    """
+
+    name: str
+    host: str
+    port: int = DEFAULT_PORT
+    dbname: str = DEFAULT_DBNAME
+    user: str = DEFAULT_USER
+    sslmode: str = DEFAULT_SSLMODE
+
+    @property
+    def password(self) -> str:
+        return _resolve_secret(self.name)
+
+    @property
+    def conn_kwargs(self) -> dict:
+        """libpq connection keyword args for ``psycopg.connect`` (incl. password)."""
+        return {
+            "host": self.host,
+            "port": self.port,
+            "dbname": self.dbname,
+            "user": self.user,
+            "password": self.password,
+            "sslmode": self.sslmode,
+            "application_name": APPLICATION_NAME,
+        }
+
+    @property
+    def dsn_redacted(self) -> str:
+        """A human-readable DSN with the password redacted (for logs/doctor)."""
+        return (
+            f"postgresql://{self.user}:***@{self.host}:{self.port}/"
+            f"{self.dbname}?sslmode={self.sslmode}"
+        )
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """Top-level application config."""
+
+    targets: tuple[TargetConfig, ...] = ()
+
+    def get_target(self, name: str) -> TargetConfig:
+        for t in self.targets:
+            if t.name == name:
+                return t
+        available = ", ".join(t.name for t in self.targets) or "(none)"
+        raise KeyError(f"Target '{name}' not found. Available: {available}")
+
+    @property
+    def default_target(self) -> TargetConfig:
+        if not self.targets:
+            raise ValueError("No targets configured. Check config.yaml")
+        return self.targets[0]
+
+
+def load_config(config_path: Path | None = None) -> AppConfig:
+    """Load config from YAML; the password comes from the encrypted store."""
+    path = config_path or CONFIG_FILE
+    if not path.exists():
+        raise FileNotFoundError(
+            f"Config file not found: {path}\n"
+            f"Run 'postgres-aiops init' to set up a target and store its password "
+            f"encrypted, or create {CONFIG_FILE} with a 'targets' list."
+        )
+
+    with open(path) as f:
+        raw = yaml.safe_load(f) or {}
+
+    targets = tuple(
+        TargetConfig(
+            name=t["name"],
+            host=t["host"],
+            port=t.get("port", DEFAULT_PORT),
+            dbname=t.get("dbname", DEFAULT_DBNAME),
+            user=t.get("user", DEFAULT_USER),
+            sslmode=t.get("sslmode", DEFAULT_SSLMODE),
+        )
+        for t in raw.get("targets", [])
+    )
+
+    return AppConfig(targets=targets)

postgres_aiops/connection.py

@@ -0,0 +1,178 @@
+"""Connection management for PostgreSQL via psycopg 3.
+
+A thin wrapper over a live libpq connection with per-target session reuse:
+
+  * Non-secret connection details (host / port / dbname / user / sslmode) come
+    from ``config.yaml``; the **password** is read from the encrypted secret
+    store (``~/.postgres-aiops/secrets.enc``) at connect time, never from disk in
+    plaintext.
+  * Reads run parameterised SQL against the system catalogs and ``pg_stat_*``
+    views; the connection is opened ``autocommit=True`` so maintenance commands
+    that cannot run inside a transaction block (``VACUUM``, ``CREATE INDEX
+    CONCURRENTLY``, ``REINDEX CONCURRENTLY``) work directly.
+  * Rows come back as dicts (``dict_row`` row factory), so the ops layer never
+    has to index columns positionally.
+
+All ``psycopg`` errors are translated centrally into ``PgError`` with a teaching
+message rather than leaking a raw traceback to an agent.
+
+The underlying connection is injectable for tests: pass ``connection=`` to
+``PgConnection`` to substitute a fake that implements ``cursor()`` / ``close()``
+— **no live database is required** to exercise the ops layer.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import psycopg
+from psycopg.rows import dict_row
+
+from postgres_aiops.config import AppConfig, TargetConfig, load_config
+
+_CONNECT_TIMEOUT = 10
+
+
+class PgError(Exception):
+    """A PostgreSQL operation failed; carries a teaching message + sqlstate."""
+
+    def __init__(self, message: str, *, sqlstate: str | None = None) -> None:
+        self.sqlstate = sqlstate
+        super().__init__(message)
+
+
+def _teaching_message(exc: psycopg.Error, target: TargetConfig) -> str:
+    """Map a psycopg error to an actionable, teaching message."""
+    sqlstate = getattr(exc, "sqlstate", None)
+    detail = str(exc).strip().splitlines()[0][:200] if str(exc) else ""
+    if isinstance(exc, psycopg.OperationalError):
+        return (
+            f"Could not connect to PostgreSQL at {target.host}:{target.port}/"
+            f"{target.dbname} as '{target.user}'. Check the host/port are reachable, "
+            f"the role/password are correct, and pg_hba.conf permits this client "
+            f"(sslmode={target.sslmode}). {detail}"
+        )
+    if sqlstate == "42P01":  # undefined_table
+        return (
+            f"Relation not found ({sqlstate}). A required catalog/view is missing — "
+            f"pg_stat_statements must be installed (CREATE EXTENSION pg_stat_statements) "
+            f"for query stats. {detail}"
+        )
+    if sqlstate == "42501":  # insufficient_privilege
+        return (
+            f"Insufficient privilege ({sqlstate}). This role lacks rights for the "
+            f"operation; a monitoring role needs pg_monitor, and maintenance "
+            f"commands need ownership. {detail}"
+        )
+    prefix = f" [{sqlstate}]" if sqlstate else ""
+    return f"PostgreSQL error{prefix} on {target.name}: {detail}"
+
+
+class PgConnection:
+    """A single authenticated session against one PostgreSQL target."""
+
+    def __init__(self, target: TargetConfig, connection: Any | None = None) -> None:
+        self._target = target
+        self._conn = connection if connection is not None else self._open(target)
+
+    @staticmethod
+    def _open(target: TargetConfig) -> Any:
+        try:
+            return psycopg.connect(
+                **target.conn_kwargs,
+                row_factory=dict_row,
+                autocommit=True,
+                connect_timeout=_CONNECT_TIMEOUT,
+            )
+        except psycopg.Error as exc:
+            raise PgError(
+                _teaching_message(exc, target), sqlstate=getattr(exc, "sqlstate", None)
+            ) from exc
+
+    @property
+    def target(self) -> TargetConfig:
+        return self._target
+
+    def query(self, sql: str, params: Any | None = None) -> list[dict]:
+        """Run a read query and return rows as a list of dicts."""
+        try:
+            with self._conn.cursor() as cur:
+                cur.execute(sql, params)
+                return [dict(r) for r in cur.fetchall()]
+        except psycopg.Error as exc:
+            raise PgError(
+                _teaching_message(exc, self._target),
+                sqlstate=getattr(exc, "sqlstate", None),
+            ) from exc
+
+    def query_one(self, sql: str, params: Any | None = None) -> dict | None:
+        """Run a read query expected to return at most one row."""
+        rows = self.query(sql, params)
+        return rows[0] if rows else None
+
+    def scalar(self, sql: str, params: Any | None = None) -> Any:
+        """Run a read query and return the first column of the first row (or None)."""
+        row = self.query_one(sql, params)
+        if not row:
+            return None
+        return next(iter(row.values()), None)
+
+    def execute(self, sql: str, params: Any | None = None) -> str:
+        """Run a write/DDL/maintenance statement; return the libpq status message."""
+        try:
+            with self._conn.cursor() as cur:
+                cur.execute(sql, params)
+                return getattr(cur, "statusmessage", "") or "OK"
+        except psycopg.Error as exc:
+            raise PgError(
+                _teaching_message(exc, self._target),
+                sqlstate=getattr(exc, "sqlstate", None),
+            ) from exc
+
+    def close(self) -> None:
+        try:
+            self._conn.close()
+        except psycopg.Error:
+            pass
+
+
+class ConnectionManager:
+    """Manages connections to multiple PostgreSQL targets with session reuse."""
+
+    def __init__(self, config: AppConfig) -> None:
+        self._config = config
+        self._connections: dict[str, PgConnection] = {}
+
+    @classmethod
+    def from_config(cls, config: AppConfig | None = None) -> ConnectionManager:
+        cfg = config or load_config()
+        return cls(cfg)
+
+    def connect(self, target_name: str | None = None) -> PgConnection:
+        """Connect to a target by name, or the default target."""
+        target = (
+            self._config.get_target(target_name)
+            if target_name
+            else self._config.default_target
+        )
+        cached = self._connections.get(target.name)
+        if cached is not None:
+            return cached
+        conn = PgConnection(target)
+        self._connections[target.name] = conn
+        return conn
+
+    def disconnect(self, target_name: str) -> None:
+        conn = self._connections.pop(target_name, None)
+        if conn is not None:
+            conn.close()
+
+    def disconnect_all(self) -> None:
+        for name in list(self._connections):
+            self.disconnect(name)
+
+    def list_targets(self) -> list[str]:
+        return [t.name for t in self._config.targets]
+
+    def list_connected(self) -> list[str]:
+        return list(self._connections.keys())

postgres_aiops/doctor.py

@@ -0,0 +1,84 @@
+"""Environment and connectivity diagnostics for Postgres AIops."""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+from postgres_aiops.config import CONFIG_FILE, ENV_FILE, load_config
+from postgres_aiops.secretstore import SECRETS_FILE, check_permissions, has_store
+
+_console = Console()
+
+
+def run_doctor(skip_auth: bool = False) -> int:
+    """Check config, secrets, and (optionally) connectivity.
+
+    Returns a process exit code: 0 healthy, 1 problems found. Connectivity
+    failures are reported as status, never raised as tracebacks (a doctor must
+    survive the thing it diagnoses being unhealthy).
+    """
+    problems = 0
+
+    if not CONFIG_FILE.exists():
+        _console.print(f"[red]✗ Config file missing: {CONFIG_FILE}[/]")
+        _console.print("[yellow]  Run 'postgres-aiops init' to set up your first target.[/]")
+        return 1
+    _console.print(f"[green]✓ Config file present: {CONFIG_FILE}[/]")
+
+    try:
+        config = load_config()
+    except Exception as exc:  # noqa: BLE001 — report, do not crash
+        _console.print(f"[red]✗ Config load failed: {exc}[/]")
+        return 1
+
+    if not config.targets:
+        _console.print("[red]✗ No targets configured[/]")
+        return 1
+    _console.print(f"[green]✓ {len(config.targets)} target(s) configured[/]")
+
+    if has_store():
+        _console.print(f"[green]✓ Encrypted secret store present: {SECRETS_FILE}[/]")
+        perm_warning = check_permissions()
+        if perm_warning:
+            _console.print(f"[yellow]! {perm_warning}[/]")
+    elif ENV_FILE.exists():
+        _console.print(
+            f"[yellow]! Using legacy plaintext .env ({ENV_FILE}). Migrate with "
+            f"'postgres-aiops secret migrate'.[/]"
+        )
+    else:
+        _console.print(
+            "[yellow]! No secret store yet. Run 'postgres-aiops init' to set up "
+            "credentials (stored encrypted).[/]"
+        )
+        problems += 1
+
+    for target in config.targets:
+        try:
+            _ = target.password
+            _console.print(f"[green]✓ password present for '{target.name}'[/]")
+        except OSError as exc:
+            _console.print(f"[red]✗ {exc}[/]")
+            problems += 1
+
+    if skip_auth:
+        _console.print("[dim]Skipping connectivity check (--skip-auth).[/]")
+        return 1 if problems else 0
+
+    from postgres_aiops.connection import ConnectionManager
+
+    mgr = ConnectionManager(config)
+    for target in config.targets:
+        try:
+            conn = mgr.connect(target.name)
+            row = conn.query_one("SELECT version() AS version") or {}
+            version = str(row.get("version", "?"))[:80]
+            _console.print(
+                f"[green]✓ Connected to '{target.name}' ({target.host}:{target.port}) "
+                f"— {version}[/]"
+            )
+        except Exception as exc:  # noqa: BLE001 — connectivity is a status, not a crash
+            _console.print(f"[red]✗ Connect to '{target.name}' failed: {exc}[/]")
+            problems += 1
+
+    return 1 if problems else 0

postgres_aiops/governance/__init__.py

@@ -0,0 +1,40 @@
+"""Governance harness for postgres-aiops — audit, policy, budget, undo, sanitize.
+
+A self-contained, vendored governance layer. postgres-aiops has NO dependency on
+any external skill family — this package is its own copy of the harness:
+
+  - ``@governed_tool`` — mandatory decorator on every MCP tool: policy pre-check,
+    token/runaway budget guard, graduated-autonomy risk-tier gate, audit logging,
+    and undo-token recording.
+  - unified SQLite audit log under ``~/.postgres-aiops/`` (override with
+    ``POSTGRES_AIOPS_HOME``).
+  - ``sanitize`` — prompt-injection defense for API-returned text.
+
+State lives under ``ops_home()`` (default ``~/.postgres-aiops``).
+"""
+
+from postgres_aiops.governance.audit import AuditEngine, get_engine
+from postgres_aiops.governance.budget import BudgetExceeded, BudgetTracker, get_budget
+from postgres_aiops.governance.decorators import PolicyDenied, governed_tool
+from postgres_aiops.governance.patterns import Pattern, PatternMatch, get_pattern_engine
+from postgres_aiops.governance.policy import TierDecision, get_policy_engine
+from postgres_aiops.governance.sanitize import sanitize
+from postgres_aiops.governance.undo import UndoStore, get_undo_store
+
+__all__ = [
+    "governed_tool",
+    "sanitize",
+    "PolicyDenied",
+    "get_engine",
+    "AuditEngine",
+    "get_policy_engine",
+    "TierDecision",
+    "get_budget",
+    "BudgetTracker",
+    "BudgetExceeded",
+    "get_undo_store",
+    "UndoStore",
+    "Pattern",
+    "PatternMatch",
+    "get_pattern_engine",
+]