plain.postgres 0.86.0__tar.gz → 0.87.0__tar.gz

{plain_postgres-0.86.0 → plain_postgres-0.87.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.86.0
+Version: 0.87.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause
@@ -23,6 +23,7 @@ Description-Content-Type: text/markdown
 - [Constraints](#constraints)
 - [Forms](#forms)
 - [Architecture](#architecture)
+- [Diagnostics](#diagnostics)
 - [Settings](#settings)
 - [FAQs](#faqs)
 - [Installation](#installation)
@@ -927,6 +928,67 @@ graph TB
 - [`SQLCompiler`](./sql/compiler.py#SQLCompiler) - Transforms a Query into executable SQL
 - [`DatabaseConnection`](./postgres/connection.py#DatabaseConnection) - PostgreSQL connection and query execution
 
+## Diagnostics
+
+You can run health checks against your database to find issues like missing indexes, redundant indexes, and configuration problems.
+
+```bash
+uv run plain postgres diagnose
+```
+
+Use `--json` for structured output (useful for scripting and AI agents):
+
+```bash
+uv run plain postgres diagnose --json
+```
+
+Use `--all` to include issues in installed packages (by default, only your app's issues are shown):
+
+```bash
+uv run plain postgres diagnose --all
+```
+
+### Checks
+
+| Check                   | What it finds                                                                                                                                                  | Severity         |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| **Invalid indexes**     | Broken indexes from failed `CREATE INDEX CONCURRENTLY` — maintained on writes, never used for reads                                                            | Warning          |
+| **Duplicate indexes**   | Indexes where one is a column-prefix of another on the same table (e.g., an auto FK index that's redundant with a composite index)                             | Warning          |
+| **Unused indexes**      | Indexes with zero scans since stats reset (>1 MB). Excludes unique indexes, constraint-backing indexes, and indexes that are the sole coverage for a FK column | Warning          |
+| **Missing FK indexes**  | Foreign key columns without any index coverage — parent DELETE/UPDATE operations will sequentially scan the child table                                        | Warning          |
+| **Sequence exhaustion** | Identity sequences approaching their type max (>50% warning, >90% critical)                                                                                    | Warning/Critical |
+| **XID wraparound**      | Transaction ID age approaching the 2 billion wraparound limit (>25% warning, >40% critical)                                                                    | Warning/Critical |
+| **Cache hit ratio**     | Heap buffer hit ratio below 98.5% — indicates insufficient `shared_buffers` or RAM                                                                             | Warning          |
+| **Index hit ratio**     | Index buffer hit ratio below 98.5%                                                                                                                             | Warning          |
+| **Vacuum health**       | Tables with significant dead tuple accumulation (>10% of live rows) where autovacuum may be falling behind                                                     | Warning          |
+
+### App vs package issues
+
+Each finding is tagged with its **source**:
+
+- **App** — your code, fully actionable
+- **Package** — owned by an installed package (e.g., `plain-jobs`). These appear in the footer summary by default; use `--all` to see details
+- **Unmanaged** — tables not managed by any Plain model. The suggestion includes exact SQL to run
+
+### Production usage
+
+Run diagnose against your **production database** to get meaningful stats. On Heroku:
+
+```bash
+heroku run -a your-app "plain postgres diagnose --json"
+```
+
+The `--json` flag must be quoted so Heroku passes it through to the command.
+
+### Preflight checks
+
+Two related checks run automatically during `uv run plain preflight` (and `uv run plain check`):
+
+- **`postgres.missing_fk_indexes`** — warns about FK fields without index coverage in your model definitions
+- **`postgres.duplicate_indexes`** — warns about prefix-redundant indexes in your model constraints
+
+These are static, code-level checks that catch issues before you deploy. The `diagnose` command complements them with runtime stats from the actual database.
+
 ## Settings
 
 Connection settings are configured via `DATABASE_URL` or individual `POSTGRES_*` settings.

{plain_postgres-0.86.0 → plain_postgres-0.87.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,19 @@
 # plain-postgres changelog
 
+## [0.87.0](https://github.com/dropseed/plain/releases/plain-postgres@0.87.0) (2026-03-25)
+
+### What's changed
+
+- **Renamed `plain db` CLI to `plain postgres`** — all subcommands (`migrate`, `diagnose`, `wait`, `backups`, etc.) are now under `plain postgres` ([a639aeacbf8d](https://github.com/dropseed/plain/commit/a639aeacbf8d))
+- **Extracted diagnose checks into `plain.postgres.diagnose` package** — the monolithic diagnose module is now split into individual check modules for better maintainability ([91f354108202](https://github.com/dropseed/plain/commit/91f354108202))
+- **FK-aware index checks** — duplicate index detection now recognizes that FK fields auto-create indexes, avoiding false positives when a composite index covers the FK column ([c116f808ac0b](https://github.com/dropseed/plain/commit/c116f808ac0b))
+- Added Diagnostics documentation section to README with check details, thresholds, and production usage guidance ([c116f808ac0b](https://github.com/dropseed/plain/commit/c116f808ac0b))
+- Show slow queries in diagnose human-readable output and fix Heroku command quoting in the diagnose skill ([6feaad54065d](https://github.com/dropseed/plain/commit/6feaad54065d))
+
+### Upgrade instructions
+
+- Replace `plain db` with `plain postgres` in all scripts, CI configs, and documentation. The old `plain db` command no longer exists.
+
 ## [0.86.0](https://github.com/dropseed/plain/releases/plain-postgres@0.86.0) (2026-03-24)
 
 ### What's changed

{plain_postgres-0.86.0 → plain_postgres-0.87.0}/plain/postgres/README.md

@@ -11,6 +11,7 @@
 - [Constraints](#constraints)
 - [Forms](#forms)
 - [Architecture](#architecture)
+- [Diagnostics](#diagnostics)
 - [Settings](#settings)
 - [FAQs](#faqs)
 - [Installation](#installation)
@@ -915,6 +916,67 @@ graph TB
 - [`SQLCompiler`](./sql/compiler.py#SQLCompiler) - Transforms a Query into executable SQL
 - [`DatabaseConnection`](./postgres/connection.py#DatabaseConnection) - PostgreSQL connection and query execution
 
+## Diagnostics
+
+You can run health checks against your database to find issues like missing indexes, redundant indexes, and configuration problems.
+
+```bash
+uv run plain postgres diagnose
+```
+
+Use `--json` for structured output (useful for scripting and AI agents):
+
+```bash
+uv run plain postgres diagnose --json
+```
+
+Use `--all` to include issues in installed packages (by default, only your app's issues are shown):
+
+```bash
+uv run plain postgres diagnose --all
+```
+
+### Checks
+
+| Check                   | What it finds                                                                                                                                                  | Severity         |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
+| **Invalid indexes**     | Broken indexes from failed `CREATE INDEX CONCURRENTLY` — maintained on writes, never used for reads                                                            | Warning          |
+| **Duplicate indexes**   | Indexes where one is a column-prefix of another on the same table (e.g., an auto FK index that's redundant with a composite index)                             | Warning          |
+| **Unused indexes**      | Indexes with zero scans since stats reset (>1 MB). Excludes unique indexes, constraint-backing indexes, and indexes that are the sole coverage for a FK column | Warning          |
+| **Missing FK indexes**  | Foreign key columns without any index coverage — parent DELETE/UPDATE operations will sequentially scan the child table                                        | Warning          |
+| **Sequence exhaustion** | Identity sequences approaching their type max (>50% warning, >90% critical)                                                                                    | Warning/Critical |
+| **XID wraparound**      | Transaction ID age approaching the 2 billion wraparound limit (>25% warning, >40% critical)                                                                    | Warning/Critical |
+| **Cache hit ratio**     | Heap buffer hit ratio below 98.5% — indicates insufficient `shared_buffers` or RAM                                                                             | Warning          |
+| **Index hit ratio**     | Index buffer hit ratio below 98.5%                                                                                                                             | Warning          |
+| **Vacuum health**       | Tables with significant dead tuple accumulation (>10% of live rows) where autovacuum may be falling behind                                                     | Warning          |
+
+### App vs package issues
+
+Each finding is tagged with its **source**:
+
+- **App** — your code, fully actionable
+- **Package** — owned by an installed package (e.g., `plain-jobs`). These appear in the footer summary by default; use `--all` to see details
+- **Unmanaged** — tables not managed by any Plain model. The suggestion includes exact SQL to run
+
+### Production usage
+
+Run diagnose against your **production database** to get meaningful stats. On Heroku:
+
+```bash
+heroku run -a your-app "plain postgres diagnose --json"
+```
+
+The `--json` flag must be quoted so Heroku passes it through to the command.
+
+### Preflight checks
+
+Two related checks run automatically during `uv run plain preflight` (and `uv run plain check`):
+
+- **`postgres.missing_fk_indexes`** — warns about FK fields without index coverage in your model definitions
+- **`postgres.duplicate_indexes`** — warns about prefix-redundant indexes in your model constraints
+
+These are static, code-level checks that catch issues before you deploy. The `diagnose` command complements them with runtime stats from the actual database.
+
 ## Settings
 
 Connection settings are configured via `DATABASE_URL` or individual `POSTGRES_*` settings.

{plain_postgres-0.86.0 → plain_postgres-0.87.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -72,6 +72,8 @@ Run `uv run plain docs postgres --section constraints` for full patterns with co
 
 Use the `/plain-postgres-diagnose` skill to run database health checks (unused indexes, missing FK indexes, sequence exhaustion, etc.).
 
+Run `uv run plain docs postgres --section diagnostics` for check details, thresholds, and production usage.
+
 ## Differences from Django
 
 - Use `Model.query` not `Model.objects`

{plain_postgres-0.86.0 → plain_postgres-0.87.0}/plain/postgres/agents/.claude/skills/plain-postgres-diagnose/SKILL.md

@@ -11,14 +11,14 @@ Run health checks against the production Postgres database and act on findings l
 
 The diagnose command should run against the **production database**, not the local dev database. Ask the user how they run commands in production if you don't know. Common patterns:
 
-- **Heroku**: `heroku run uv run plain db diagnose --json -a app-name`
-- **Direct**: `uv run plain db diagnose --json` (if DATABASE_URL points to production)
+- **Heroku**: `heroku run -a app-name "plain postgres diagnose --json"`
+- **Direct**: `uv run plain postgres diagnose --json` (if DATABASE_URL points to production)
 - **Other platforms**: wrap with the platform's run command
 
 For local/dev analysis, run directly:
 
 ```
-uv run plain db diagnose --json
+uv run plain postgres diagnose --json
 ```
 
 ## 2. Interpret the JSON output

plain_postgres-0.87.0/plain/postgres/cli/__init__.py

@@ -0,0 +1,3 @@
+from . import core, migrations
+
+__all__ = ["core", "migrations"]

plain_postgres-0.86.0/plain/postgres/cli/db.py → plain_postgres-0.87.0/plain/postgres/cli/core.py

@@ -17,10 +17,10 @@ from ..migrations.recorder import MIGRATION_TABLE_NAME
 from .diagnose import diagnose
 
 
-@register_cli("db")
+@register_cli("postgres")
 @click.group()
 def cli() -> None:
-    """Database operations"""
+    """Postgres operations"""
 
 
 cli.add_command(backups_cli)

plain_postgres-0.87.0/plain/postgres/cli/diagnose.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import click
+
+from ..db import get_connection
+from ..diagnose import CheckItem, CheckResult, build_table_owners, run_all_checks
+
+STATUS_SYMBOLS = {
+    "ok": ("✓", "green"),
+    "warning": ("!", "yellow"),
+    "critical": ("!!", "red"),
+    "skipped": ("—", None),
+    "error": ("✗", "red"),
+}
+
+
+def format_human(
+    results: list[CheckResult],
+    context: dict[str, Any],
+    *,
+    show_all: bool = False,
+) -> None:
+    # Split items into actionable (app + unmanaged) vs package
+    def _actionable_items(r: CheckResult) -> list[CheckItem]:
+        return [i for i in r["items"] if i["source"] != "package"]
+
+    def _package_items(r: CheckResult) -> list[CheckItem]:
+        return [i for i in r["items"] if i["source"] == "package"]
+
+    # Compute effective status (only actionable items trigger warnings unless --all)
+    def _effective_status(r: CheckResult) -> str:
+        if show_all:
+            return r["status"]
+        if r["status"] in ("ok", "skipped", "error"):
+            return r["status"]
+        if r["items"] and not _actionable_items(r):
+            return "ok"
+        return r["status"]
+
+    # Summary table
+    label_width = max(len(r["label"]) for r in results)
+    summaries: list[str] = []
+    for r in results:
+        if _effective_status(r) == r["status"]:
+            summaries.append(r["summary"])
+        else:
+            summaries.append("ok")
+    summary_width = max(len(s) for s in summaries)
+
+    click.echo()
+    for r, summary_text in zip(results, summaries):
+        status = _effective_status(r)
+        symbol, color = STATUS_SYMBOLS.get(status, ("?", None))
+        label = r["label"].ljust(label_width)
+        summary = summary_text.ljust(summary_width)
+        click.echo(f"  {label}  {summary}  ", nl=False)
+        click.secho(symbol, fg=color)
+
+    # Counts
+    statuses = [_effective_status(r) for r in results]
+    ok_count = statuses.count("ok")
+    warn_count = statuses.count("warning")
+    critical_count = statuses.count("critical")
+    error_count = statuses.count("error")
+
+    parts = []
+    if ok_count:
+        parts.append(f"{ok_count} passed")
+    if warn_count:
+        parts.append(f"{warn_count} warnings")
+    if critical_count:
+        parts.append(f"{critical_count} critical")
+    if error_count:
+        parts.append(f"{error_count} errors")
+    click.echo(f"\n  {', '.join(parts)}")
+
+    # Details
+    for r in results:
+        if _effective_status(r) in ("ok", "skipped"):
+            continue
+
+        items_to_show = r["items"] if show_all else _actionable_items(r)
+        if items_to_show:
+            click.echo()
+            click.secho(f"  {r['label']}", bold=True)
+            for item in items_to_show:
+                if item["table"]:
+                    line = f"    {item['name']} on {item['table']} ({item['detail']})"
+                else:
+                    line = f"    {item['name']} ({item['detail']})"
+
+                if item["source"] == "package":
+                    click.secho(line, dim=True)
+                    click.secho(
+                        f"      {item['package']} package — not your code",
+                        dim=True,
+                    )
+                else:
+                    if item["source"] == "app" and item["package"]:
+                        click.echo(f"{line}  [{item['package']}]")
+                    else:
+                        click.echo(line)
+                    click.secho(f"      {item['suggestion']}", dim=True)
+
+        if r["message"]:
+            click.echo()
+            click.secho(f"  {r['label']}: {r['message']}", bold=True)
+
+    # Package issues footnote (only when not --all)
+    all_package_items: list[tuple[str, CheckItem]] = []
+    if not show_all:
+        for r in results:
+            for item in _package_items(r):
+                all_package_items.append((r["label"], item))
+
+    if all_package_items:
+        click.echo()
+        # Group by package
+        by_package: dict[str, list[tuple[str, CheckItem]]] = {}
+        for check_label, item in all_package_items:
+            by_package.setdefault(item["package"], []).append((check_label, item))
+
+        pkg_parts = []
+        for pkg, items in sorted(by_package.items()):
+            check_names = sorted({label.lower() for label, _ in items})
+            pkg_parts.append(f"{pkg} ({len(items)} — {', '.join(check_names)})")
+
+        click.secho(
+            f"  Also found {len(all_package_items)} issues in installed packages: {'; '.join(pkg_parts)}",
+            dim=True,
+        )
+
+    # Slow queries
+    slow_queries = context.get("slow_queries", [])
+    if slow_queries:
+        click.echo()
+        click.secho("  Slowest queries (by total time)", bold=True)
+        for q in slow_queries:
+            click.echo(
+                f"    {q['total_time_ms']:>10.0f}ms total"
+                f"  {q['mean_time_ms']:>8.0f}ms avg"
+                f"  {q['calls']:>8,} calls"
+                f"  ({q['pct_total_time']:.1f}%)"
+            )
+            query_preview = q["query"].replace("\n", " ").strip()
+            click.secho(f"      {query_preview}", dim=True)
+
+    # Footer
+    click.echo()
+    stats_reset = context.get("stats_reset")
+    click.secho(
+        f"  Stats reset: {stats_reset[:10] if stats_reset else 'never'}",
+        dim=True,
+    )
+
+    pgss = context.get("pg_stat_statements")
+    if pgss == "not_installed":
+        click.secho(
+            "  pg_stat_statements: not installed (install for query analysis)",
+            dim=True,
+        )
+    elif pgss == "no_permission":
+        click.secho(
+            "  pg_stat_statements: installed but not accessible (insufficient privileges)",
+            dim=True,
+        )
+
+    conn = context.get("connections", {})
+    if conn:
+        pct = round(100 * conn["active"] / conn["max"]) if conn["max"] else 0
+        click.secho(f"  Connections: {conn['active']}/{conn['max']} ({pct}%)", dim=True)
+
+    click.echo()
+
+
+@click.command()
+@click.option("--json", "output_json", is_flag=True, help="Output as JSON")
+@click.option(
+    "--all", "show_all", is_flag=True, help="Include package issues in detail"
+)
+def diagnose(output_json: bool, show_all: bool) -> None:
+    """Run health checks against the database"""
+    conn = get_connection()
+    table_owners = build_table_owners()
+
+    with conn.cursor() as cursor:
+        results, context = run_all_checks(cursor, table_owners)
+
+    if output_json:
+        output = {
+            "checks": results,
+            "context": context,
+        }
+        click.echo(json.dumps(output, indent=2, default=str))
+    else:
+        format_human(results, context, show_all=show_all)
+
+    # Exit 1 if any critical
+    if any(r["status"] == "critical" for r in results):
+        sys.exit(1)

plain_postgres-0.87.0/plain/postgres/diagnose/__init__.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+from typing import Any
+
+from .checks import ALL_CHECKS
+from .context import gather_context
+from .tables import build_table_owners
+from .types import CheckItem, CheckResult, TableOwner
+
+__all__ = [
+    "ALL_CHECKS",
+    "CheckItem",
+    "CheckResult",
+    "TableOwner",
+    "build_table_owners",
+    "gather_context",
+    "run_all_checks",
+]
+
+
+def run_all_checks(
+    cursor: Any, table_owners: dict[str, TableOwner]
+) -> tuple[list[CheckResult], dict[str, Any]]:
+    results: list[CheckResult] = []
+    for check_fn in ALL_CHECKS:
+        try:
+            result = check_fn(cursor, table_owners)
+        except Exception as e:
+            result = CheckResult(
+                name=check_fn.__name__.removeprefix("check_"),
+                label=check_fn.__name__.removeprefix("check_")
+                .replace("_", " ")
+                .title(),
+                status="error",
+                summary="error",
+                items=[],
+                message=str(e),
+            )
+        results.append(result)
+
+    context = gather_context(cursor, table_owners)
+    return results, context