plain.postgres 0.85.0__tar.gz → 0.86.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.85.0
+Version: 0.86.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause

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

@@ -1,5 +1,17 @@
 # plain-postgres changelog
 
+## [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.86.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -68,6 +68,10 @@ 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.).
+
 ## Differences from Django
 
 - Use `Model.query` not `Model.objects`

plain_postgres-0.86.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 uv run plain db diagnose --json -a app-name`
+- **Direct**: `uv run plain db 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
+```
+
+## 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.85.0 → plain_postgres-0.86.0}/plain/postgres/cli/db.py

@@ -14,6 +14,7 @@ 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")
@@ -23,6 +24,7 @@ def cli() -> None:
 
 
 cli.add_command(backups_cli)
+cli.add_command(diagnose)
 
 
 @cli.command()