postgres-aiops 0.1.0__py3-none-any.whl

postgres_aiops/cli/analyze.py

@@ -0,0 +1,53 @@
+"""``postgres-aiops analyze`` — the three flagship analyses (pull live)."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from postgres_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+analyze_app = typer.Typer(
+    name="analyze",
+    help="Flagship analyses: slow-query RCA, bloat/vacuum, blocking chains.",
+    no_args_is_help=True,
+)
+
+
+@analyze_app.command("slow-query")
+@cli_errors
+def analyze_slow_query(
+    explain_sql: Annotated[str | None, typer.Option("--explain", help="SQL to EXPLAIN")] = None,
+    target: TargetOption = None,
+) -> None:
+    """Root-cause the worst pg_stat_statements entry."""
+    from postgres_aiops.ops import analysis, queries
+
+    conn, _ = get_connection(target)
+    statements = queries.top_queries(conn, order_by="total_time")["statements"]
+    explain = queries.explain_query(conn, explain_sql) if explain_sql else None
+    console.print_json(json.dumps(analysis.slow_query_rca(statements, explain=explain)))
+
+
+@analyze_app.command("bloat-vacuum")
+@cli_errors
+def analyze_bloat_vacuum(target: TargetOption = None) -> None:
+    """Rank tables needing vacuum from dead-tuple ratio + autovacuum recency."""
+    from postgres_aiops.ops import analysis, tables
+
+    conn, _ = get_connection(target)
+    rows = tables.table_bloat(conn)["tables"]
+    console.print_json(json.dumps(analysis.bloat_and_vacuum_analysis(rows)))
+
+
+@analyze_app.command("blocking")
+@cli_errors
+def analyze_blocking(target: TargetOption = None) -> None:
+    """Build the blocking-lock chain and name the root blocker."""
+    from postgres_aiops.ops import activity, analysis
+
+    conn, _ = get_connection(target)
+    pairs = activity.blocking_pairs(conn)
+    console.print_json(json.dumps(analysis.blocking_lock_chain_rca(pairs)))

postgres_aiops/cli/doctor.py

@@ -0,0 +1,21 @@
+"""Doctor top-level command: environment and connectivity check."""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+import typer
+
+from postgres_aiops.cli._common import cli_errors
+
+
+@cli_errors
+def doctor_cmd(
+    skip_auth: Annotated[
+        bool, typer.Option("--skip-auth", help="Skip connectivity check (faster)")
+    ] = False,
+) -> None:
+    """Check environment, config, secrets, and connectivity."""
+    from postgres_aiops.doctor import run_doctor
+
+    raise typer.Exit(run_doctor(skip_auth=skip_auth))

postgres_aiops/cli/index.py

@@ -0,0 +1,55 @@
+"""``postgres-aiops index`` — index-health reads."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from postgres_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+index_app = typer.Typer(
+    name="index",
+    help="Index health: unused, missing, bloat, invalid.",
+    no_args_is_help=True,
+)
+
+
+@index_app.command("unused")
+@cli_errors
+def index_unused(target: TargetOption = None) -> None:
+    """Non-unique, non-primary indexes with zero scans."""
+    from postgres_aiops.ops import indexes as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.unused_indexes(conn)))
+
+
+@index_app.command("missing")
+@cli_errors
+def index_missing(target: TargetOption = None) -> None:
+    """Tables with heavy sequential scans (missing-index hints)."""
+    from postgres_aiops.ops import indexes as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.missing_index_hints(conn)))
+
+
+@index_app.command("bloat")
+@cli_errors
+def index_bloat(target: TargetOption = None) -> None:
+    """Coarse index-bloat estimate."""
+    from postgres_aiops.ops import indexes as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.index_bloat(conn)))
+
+
+@index_app.command("invalid")
+@cli_errors
+def index_invalid(target: TargetOption = None) -> None:
+    """Invalid and duplicate indexes."""
+    from postgres_aiops.ops import indexes as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.invalid_indexes(conn)))

postgres_aiops/cli/init.py

@@ -0,0 +1,112 @@
+"""``postgres-aiops init`` — a friendly, interactive onboarding wizard.
+
+Walks a new user through connecting their first PostgreSQL target: collects the
+non-secret connection details into ``config.yaml`` and the role password into the
+*encrypted* store (never plaintext on disk). Designed to be run on a terminal;
+everything it needs is prompted with sensible defaults.
+"""
+
+from __future__ import annotations
+
+import getpass
+
+import typer
+import yaml
+
+from postgres_aiops.cli._common import cli_errors, console
+from postgres_aiops.config import (
+    CONFIG_DIR,
+    CONFIG_FILE,
+    DEFAULT_DBNAME,
+    DEFAULT_PORT,
+    DEFAULT_SSLMODE,
+    DEFAULT_USER,
+)
+from postgres_aiops.secretstore import SecretStore, resolve_master_password
+
+
+def _load_existing_targets() -> list[dict]:
+    if not CONFIG_FILE.exists():
+        return []
+    raw = yaml.safe_load(CONFIG_FILE.read_text("utf-8")) or {}
+    return list(raw.get("targets", []))
+
+
+def _write_targets(targets: list[dict]) -> None:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    try:
+        CONFIG_DIR.chmod(0o700)
+    except OSError:
+        pass
+    CONFIG_FILE.write_text(yaml.safe_dump({"targets": targets}, sort_keys=False), "utf-8")
+
+
+@cli_errors
+def init_cmd() -> None:
+    """Interactively set up your first PostgreSQL connection."""
+    console.print("[bold cyan]Postgres AIops — setup wizard[/]")
+    console.print(
+        "This collects connection details (saved to config.yaml) and your "
+        "PostgreSQL password (saved [bold]encrypted[/] to secrets.enc).\n"
+    )
+
+    console.print("[bold]Step 1 — master password[/]")
+    console.print(
+        "[dim]Encrypts secrets.enc. You'll set it via the "
+        "POSTGRES_AIOPS_MASTER_PASSWORD env var for non-interactive/MCP use.[/]"
+    )
+    password = resolve_master_password(confirm_if_new=True)
+    store = SecretStore.unlock(password)
+
+    targets = _load_existing_targets()
+    existing_names = {t.get("name") for t in targets}
+
+    while True:
+        console.print("\n[bold]Step 2 — add a target[/]")
+        name = typer.prompt("Target name (e.g. primary)").strip()
+        if name in existing_names:
+            if not typer.confirm(f"'{name}' already exists — overwrite?", default=False):
+                continue
+            targets = [t for t in targets if t.get("name") != name]
+
+        host = typer.prompt("Host (IP or FQDN of the PostgreSQL server)").strip()
+        port = typer.prompt("Port", default=DEFAULT_PORT, type=int)
+        dbname = typer.prompt("Database name", default=DEFAULT_DBNAME).strip()
+        user = typer.prompt("Role/user", default=DEFAULT_USER).strip()
+        sslmode = typer.prompt(
+            "sslmode (disable/allow/prefer/require/verify-ca/verify-full)",
+            default=DEFAULT_SSLMODE,
+        ).strip()
+
+        console.print(
+            "[dim]The role should have pg_monitor for read visibility. "
+            "Enter its password below (input hidden).[/]"
+        )
+        secret = getpass.getpass(f"Password for '{user}'@'{name}' (hidden): ")
+        store = store.set(name, secret)
+
+        entry = {
+            "name": name,
+            "host": host,
+            "port": port,
+            "dbname": dbname,
+            "user": user,
+            "sslmode": sslmode,
+        }
+        targets.append(entry)
+        existing_names.add(name)
+        _write_targets(targets)
+        console.print(f"[green]✓ Saved target '{name}' (password stored encrypted).[/]")
+
+        if not typer.confirm("\nAdd another target?", default=False):
+            break
+
+    console.print(f"\n[green]✓ Setup complete.[/] Config: {CONFIG_FILE}")
+    console.print(
+        "[dim]Tip: export POSTGRES_AIOPS_MASTER_PASSWORD=... in your shell profile "
+        "so the MCP server and CLI can unlock secrets non-interactively.[/]"
+    )
+    if typer.confirm("Run a connectivity check now (postgres-aiops doctor)?", default=True):
+        from postgres_aiops.doctor import run_doctor
+
+        raise typer.Exit(run_doctor())

postgres_aiops/cli/overview.py

@@ -0,0 +1,16 @@
+"""``postgres-aiops overview`` — one-shot cluster health snapshot."""
+
+from __future__ import annotations
+
+import json
+
+from postgres_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+
+@cli_errors
+def overview_cmd(target: TargetOption = None) -> None:
+    """One-shot cluster health: version, connections, long queries, bloat, replication."""
+    from postgres_aiops.ops import overview as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.snapshot(conn)))

postgres_aiops/cli/query.py

@@ -0,0 +1,70 @@
+"""``postgres-aiops query`` — pg_stat_statements top-N, EXPLAIN, stats reset."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from postgres_aiops.cli._common import (
+    DryRunOption,
+    TargetOption,
+    cli_errors,
+    console,
+    double_confirm,
+    dry_run_print,
+    get_connection,
+)
+
+query_app = typer.Typer(
+    name="query",
+    help="Query stats: top-N, EXPLAIN, reset.",
+    no_args_is_help=True,
+)
+
+
+@query_app.command("top")
+@cli_errors
+def query_top(
+    order_by: Annotated[
+        str, typer.Option("--order-by", help="total_time|mean_time|calls|rows|io")
+    ] = "total_time",
+    limit: Annotated[int, typer.Option("--limit", help="Rows to return")] = 20,
+    target: TargetOption = None,
+) -> None:
+    """Top statements from pg_stat_statements."""
+    from postgres_aiops.ops import queries as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.top_queries(conn, order_by=order_by, limit=limit)))
+
+
+@query_app.command("explain")
+@cli_errors
+def query_explain(
+    sql: Annotated[str, typer.Argument(help="A single SQL statement to EXPLAIN")],
+    analyze: Annotated[
+        bool, typer.Option("--analyze", help="Execute to gather real timing")
+    ] = False,
+    target: TargetOption = None,
+) -> None:
+    """Return the JSON execution plan for a statement."""
+    from postgres_aiops.ops import queries as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.explain_query(conn, sql, analyze=analyze)))
+
+
+@query_app.command("reset")
+@cli_errors
+def query_reset(target: TargetOption = None, dry_run: DryRunOption = False) -> None:
+    """Reset pg_stat_statements accumulators (irreversible; dry-run + confirm)."""
+    from postgres_aiops.ops import queries as ops
+
+    if dry_run:
+        dry_run_print(operation="reset_query_stats", api_call="SELECT pg_stat_statements_reset()")
+        return
+    double_confirm("reset pg_stat_statements on", "this target")
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.reset_query_stats(conn)))

postgres_aiops/cli/remediate.py

@@ -0,0 +1,186 @@
+"""``postgres-aiops remediate`` — guarded maintenance writes (dry-run + confirm)."""
+
+from __future__ import annotations
+
+import json
+from typing import Annotated
+
+import typer
+
+from postgres_aiops.cli._common import (
+    DryRunOption,
+    TargetOption,
+    cli_errors,
+    console,
+    double_confirm,
+    dry_run_print,
+    get_connection,
+)
+
+remediate_app = typer.Typer(
+    name="remediate",
+    help="Guarded writes: terminate/cancel, vacuum/analyze, index ops, ALTER SYSTEM.",
+    no_args_is_help=True,
+)
+
+
+@remediate_app.command("terminate")
+@cli_errors
+def remediate_terminate(
+    pid: Annotated[int, typer.Argument(help="Backend pid to terminate")],
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """Terminate a backend (no undo; dry-run + confirm)."""
+    from postgres_aiops.ops import remediation as ops
+
+    if dry_run:
+        dry_run_print(operation="terminate_backend",
+                      api_call="SELECT pg_terminate_backend(pid)", parameters={"pid": pid})
+        return
+    double_confirm("terminate backend", str(pid))
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.terminate_backend(conn, pid)))
+
+
+@remediate_app.command("cancel")
+@cli_errors
+def remediate_cancel(
+    pid: Annotated[int, typer.Argument(help="Backend pid whose query to cancel")],
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """Cancel a backend's running query (no undo; dry-run + confirm)."""
+    from postgres_aiops.ops import remediation as ops
+
+    if dry_run:
+        dry_run_print(operation="cancel_query",
+                      api_call="SELECT pg_cancel_backend(pid)", parameters={"pid": pid})
+        return
+    double_confirm("cancel query on backend", str(pid))
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.cancel_query(conn, pid)))
+
+
+@remediate_app.command("vacuum")
+@cli_errors
+def remediate_vacuum(
+    table: Annotated[str, typer.Argument(help="Table (optionally schema-qualified)")],
+    full: Annotated[bool, typer.Option("--full", help="VACUUM FULL (exclusive lock)")] = False,
+    analyze: Annotated[bool, typer.Option("--analyze", help="Also ANALYZE")] = False,
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """VACUUM a table (dry-run + confirm)."""
+    from postgres_aiops.ops import remediation as ops
+
+    if dry_run:
+        dry_run_print(operation="run_vacuum", api_call=f"VACUUM {table}",
+                      parameters={"full": full, "analyze": analyze})
+        return
+    double_confirm("VACUUM", table)
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.run_vacuum(conn, table, full=full, analyze=analyze)))
+
+
+@remediate_app.command("analyze-table")
+@cli_errors
+def remediate_analyze(
+    table: Annotated[str, typer.Argument(help="Table (optionally schema-qualified)")],
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """ANALYZE a table (dry-run + confirm)."""
+    from postgres_aiops.ops import remediation as ops
+
+    if dry_run:
+        dry_run_print(operation="run_analyze", api_call=f"ANALYZE {table}")
+        return
+    double_confirm("ANALYZE", table)
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.run_analyze(conn, table)))
+
+
+@remediate_app.command("create-index")
+@cli_errors
+def remediate_create_index(
+    table: Annotated[str, typer.Argument(help="Table to index")],
+    columns: Annotated[list[str], typer.Argument(help="Column(s) to index")],
+    name: Annotated[str | None, typer.Option("--name", help="Index name")] = None,
+    unique: Annotated[bool, typer.Option("--unique", help="UNIQUE index")] = False,
+    concurrently: Annotated[bool, typer.Option("--concurrently", help="CONCURRENTLY")] = False,
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """Create an index (reversible; dry-run + confirm)."""
+    from postgres_aiops.ops import remediation as ops
+
+    if dry_run:
+        dry_run_print(operation="create_index", api_call=f"CREATE INDEX ON {table}",
+                      parameters={"columns": columns, "name": name, "unique": unique})
+        return
+    double_confirm("create index on", table)
+    conn, _ = get_connection(target)
+    result = ops.create_index(conn, table, columns, name=name, unique=unique,
+                              concurrently=concurrently)
+    console.print_json(json.dumps(result))
+
+
+@remediate_app.command("drop-index")
+@cli_errors
+def remediate_drop_index(
+    name: Annotated[str, typer.Argument(help="Index name to drop")],
+    concurrently: Annotated[bool, typer.Option("--concurrently", help="CONCURRENTLY")] = False,
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """Drop an index (reversible; captures the definition first; dry-run + confirm)."""
+    from postgres_aiops.ops import remediation as ops
+
+    if dry_run:
+        dry_run_print(operation="drop_index", api_call=f"DROP INDEX {name}")
+        return
+    double_confirm("drop index", name)
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.drop_index(conn, name, concurrently=concurrently)))
+
+
+@remediate_app.command("reindex")
+@cli_errors
+def remediate_reindex(
+    target_name: Annotated[str, typer.Argument(help="Index/table/schema name")],
+    kind: Annotated[str, typer.Option("--kind", help="INDEX|TABLE|SCHEMA")] = "INDEX",
+    concurrently: Annotated[bool, typer.Option("--concurrently", help="CONCURRENTLY")] = False,
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """REINDEX an index/table/schema (dry-run + confirm)."""
+    from postgres_aiops.ops import remediation as ops
+
+    if dry_run:
+        dry_run_print(operation="reindex", api_call=f"REINDEX {kind} {target_name}")
+        return
+    double_confirm(f"REINDEX {kind}", target_name)
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.reindex(conn, target_name, kind=kind,
+                                              concurrently=concurrently)))
+
+
+@remediate_app.command("set")
+@cli_errors
+def remediate_set(
+    name: Annotated[str, typer.Argument(help="Parameter name (e.g. work_mem)")],
+    value: Annotated[str, typer.Argument(help="New value")],
+    target: TargetOption = None,
+    dry_run: DryRunOption = False,
+) -> None:
+    """ALTER SYSTEM SET a parameter (reversible; dry-run + confirm)."""
+    from postgres_aiops.ops import remediation as ops
+
+    if dry_run:
+        dry_run_print(operation="update_setting",
+                      api_call=f"ALTER SYSTEM SET {name} = ...", parameters={"value": value})
+        return
+    double_confirm(f"ALTER SYSTEM SET {name} =", value)
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.update_setting(conn, name, value)))

postgres_aiops/cli/replication.py

@@ -0,0 +1,45 @@
+"""``postgres-aiops repl`` — replication reads."""
+
+from __future__ import annotations
+
+import json
+
+import typer
+
+from postgres_aiops.cli._common import TargetOption, cli_errors, console, get_connection
+
+repl_app = typer.Typer(
+    name="repl",
+    help="Replication: status, slots, WAL.",
+    no_args_is_help=True,
+)
+
+
+@repl_app.command("status")
+@cli_errors
+def repl_status(target: TargetOption = None) -> None:
+    """Connected standbys and replay lag."""
+    from postgres_aiops.ops import replication as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.replication_status(conn)))
+
+
+@repl_app.command("slots")
+@cli_errors
+def repl_slots(target: TargetOption = None) -> None:
+    """Replication slots (inactive slots flagged)."""
+    from postgres_aiops.ops import replication as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.replication_slots(conn)))
+
+
+@repl_app.command("wal")
+@cli_errors
+def repl_wal(target: TargetOption = None) -> None:
+    """WAL position, level and archiver health."""
+    from postgres_aiops.ops import replication as ops
+
+    conn, _ = get_connection(target)
+    console.print_json(json.dumps(ops.wal_status(conn)))

postgres_aiops/cli/secret.py

@@ -0,0 +1,103 @@
+"""``postgres-aiops secret`` — manage the encrypted credential store.
+
+Secrets (PostgreSQL role passwords) are stored in ``~/.postgres-aiops/secrets.enc``
+(Fernet, key derived from a master password via scrypt). Nothing here ever
+prints a secret value.
+"""
+
+from __future__ import annotations
+
+import getpass
+from typing import Annotated
+
+import typer
+
+from postgres_aiops.cli._common import cli_errors, console
+from postgres_aiops.config import SECRET_ENV_PREFIX, SECRET_ENV_SUFFIX
+from postgres_aiops.secretstore import (
+    SECRETS_FILE,
+    SecretStore,
+    check_permissions,
+    migrate_legacy_env,
+    resolve_master_password,
+)
+
+secret_app = typer.Typer(
+    name="secret",
+    help="Manage the encrypted credential store (secrets.enc).",
+    no_args_is_help=True,
+)
+
+NameArg = Annotated[str, typer.Argument(help="Target name the password belongs to")]
+
+
+@secret_app.command("set")
+@cli_errors
+def secret_set(
+    name: NameArg,
+    value: Annotated[
+        str | None,
+        typer.Option("--value", help="Password value (omit to be prompted, hidden)"),
+    ] = None,
+) -> None:
+    """Store (or replace) the password for a target — value is read hidden."""
+    password = resolve_master_password(confirm_if_new=True)
+    if value is None:
+        value = getpass.getpass(f"Password for '{name}' (hidden): ")
+    store = SecretStore.unlock(password)
+    store.set(name, value)
+    console.print(f"[green]✓ Stored encrypted password for '{name}' in {SECRETS_FILE}[/]")
+
+
+@secret_app.command("list")
+@cli_errors
+def secret_list() -> None:
+    """List target names that have a stored password (values never shown)."""
+    store = SecretStore.unlock()
+    names = store.names()
+    if not names:
+        console.print("[yellow]No secrets stored yet. Add one: postgres-aiops secret set <name>[/]")
+        return
+    console.print("[bold]Stored secrets:[/]")
+    for n in names:
+        console.print(f"  • {n}")
+    warning = check_permissions()
+    if warning:
+        console.print(f"[yellow]! {warning}[/]")
+
+
+@secret_app.command("rm")
+@cli_errors
+def secret_rm(name: NameArg) -> None:
+    """Delete a stored password."""
+    store = SecretStore.unlock()
+    store.delete(name)
+    console.print(f"[green]✓ Deleted password for '{name}'[/]")
+
+
+@secret_app.command("migrate")
+@cli_errors
+def secret_migrate() -> None:
+    """Import passwords from a legacy plaintext .env into the encrypted store."""
+    password = resolve_master_password(confirm_if_new=True)
+    imported = migrate_legacy_env(SECRET_ENV_PREFIX, SECRET_ENV_SUFFIX, password)
+    if not imported:
+        console.print("[yellow]Nothing to migrate (no legacy .env secrets found).[/]")
+        return
+    console.print(f"[green]✓ Imported {len(imported)} secret(s): {', '.join(imported)}[/]")
+    console.print("[dim]The old .env was renamed to .env.migrated — delete it once verified.[/]")
+
+
+@secret_app.command("rotate-password")
+@cli_errors
+def secret_rotate_password() -> None:
+    """Re-encrypt the whole store under a new master password."""
+    console.print("[bold]Unlock with the current master password:[/]")
+    store = SecretStore.unlock()
+    new_pw = getpass.getpass("New master password: ")
+    confirm = getpass.getpass("Confirm new master password: ")
+    if new_pw != confirm:
+        console.print("[red]Passwords did not match. Aborted.[/]")
+        raise typer.Exit(1)
+    store.with_password(new_pw)
+    console.print("[green]✓ Master password rotated. Update POSTGRES_AIOPS_MASTER_PASSWORD.[/]")