plain.postgres 0.85.0__tar.gz → 0.87.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.85.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.85.0 → plain_postgres-0.87.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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
+
+- **New `plain db diagnose` command** — runs health checks against your Postgres database and reports issues as structured JSON. Checks for unused indexes, duplicate indexes, missing foreign key indexes, sequence exhaustion, transaction ID wraparound, vacuum health, and slow queries (via `pg_stat_statements`). Each finding includes table ownership info (app vs package) and actionable suggestions ([91994604b60d](https://github.com/dropseed/plain/commit/91994604b60d))
+- **New preflight checks** for missing foreign key indexes and duplicate indexes — these run automatically during `plain check` and flag issues before they hit production ([3703fe8ab38d](https://github.com/dropseed/plain/commit/3703fe8ab38d))
+- New `plain-postgres-diagnose` AI skill for guided database health check workflow ([91994604b60d](https://github.com/dropseed/plain/commit/91994604b60d))
+
+### Upgrade instructions
+
+- No changes required.
+
 ## [0.85.0](https://github.com/dropseed/plain/releases/plain-postgres@0.85.0) (2026-03-22)
 
 ### What's changed

{plain_postgres-0.85.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.85.0 → plain_postgres-0.87.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -68,6 +68,12 @@ Run `uv run plain docs postgres --section querying` for full patterns with code
 
 Run `uv run plain docs postgres --section constraints` for full patterns with code examples.
 
+## Diagnostics
+
+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.87.0/plain/postgres/agents/.claude/skills/plain-postgres-diagnose/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: plain-postgres-diagnose
+description: Run Postgres health checks and fix issues. Use when asked to check database health, optimize the database, find unused indexes, or diagnose Postgres problems.
+---
+
+# Database Diagnostics
+
+Run health checks against the production Postgres database and act on findings locally.
+
+## 1. Determine how to run the command
+
+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 -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 postgres diagnose --json
+```
+
+## 2. Interpret the JSON output
+
+The output has two sections:
+
+**`checks`** — an array of health check results, each with:
+
+- `name` — check identifier
+- `status` — `ok`, `warning`, `critical`, `skipped`, or `error`
+- `items` — specific findings, each with:
+    - `table`, `name`, `detail` — what was found
+    - `source` — `"app"` (user's code), `"package"` (framework/third-party dependency), or `""` (unmanaged)
+    - `package` — the package label (e.g., `"jobs"`, `"observer"`) if source is `"package"`
+    - `suggestion` — what to do about it
+- `message` — additional context
+
+**`context`** — supporting information:
+
+- `tables` — all tables with row counts, sizes, index counts, `source`, and `package`
+- `connections` — active vs max connections
+- `stats_reset` — when pg_stat_user_indexes was last reset (affects "unused" interpretation)
+- `pg_stat_statements` — whether query analysis is available
+- `slow_queries` — top 10 queries by total execution time (if available)
+
+## 3. Fix issues
+
+Get the JSON results from production, then make fixes locally in the codebase.
+
+Process checks in priority order: critical first, then warnings.
+
+**App items** (`source: "app"`): The user's own code. Fully actionable:
+
+- Unused/duplicate indexes → find the index in the model's constraints, remove it, run `uv run plain makemigrations`
+- Missing FK indexes → add an Index to the model, run `uv run plain makemigrations`
+
+**Package items** (`source: "package"`): Owned by a framework or third-party package. Present these to the user with context:
+
+- **Duplicate indexes** on package tables are likely framework bugs — mention them so the user is aware, and suggest reporting upstream
+- **Unused indexes** on package tables may support features the app hasn't activated yet — these are not necessarily problems. Note them but don't recommend removal
+
+**Unmanaged items** (`source: ""`): Tables not owned by any Plain model. Use direct SQL:
+
+- Run the `suggestion` SQL directly (the command provides exact DDL)
+
+**Operational issues** (sequence exhaustion, XID wraparound, vacuum health):
+
+- These require direct database operations regardless of source
+- For sequence exhaustion, alter the column type and create a migration
+- For XID wraparound, investigate autovacuum configuration
+- For vacuum health, check if autovacuum is keeping up
+
+## 4. Re-run to verify
+
+After deploying changes, run the diagnose command again on production to confirm the issues are resolved.

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

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

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

@@ -14,15 +14,17 @@ from ..backups.cli import cli as backups_cli
 from ..db import get_connection
 from ..dialect import quote_name
 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)
+cli.add_command(diagnose)
 
 
 @cli.command()

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