// Check overall database health — schema correctness and operational health. Use when asked to check the database, validate schema, optimize indexes, or diagnose Postgres problems.
Upgrades Plain packages and applies required migration changes. Use when updating to newer package versions.
Captures and analyzes performance traces to identify slow queries and N+1 problems. Use when a page is slow, there are too many queries, or the user asks about performance.
Answer questions about the Plain framework by researching docs and source code. Use when asked "how do I...", "does Plain support...", or "how does X work?" questions.
Submit a bug report for the Plain framework. Use when the user wants to report a bug, error, or unexpected behavior. Collects context and creates a GitHub issue.
Open a remote Python shell on a production machine via encrypted tunnel. Use when you need to inspect production data, debug issues, run queries, or transfer files.
Releases Plain packages with intelligent version suggestions and parallel release notes generation. Use when releasing packages to PyPI.
| name | plain-postgres-doctor |
| description | Check overall database health — schema correctness and operational health. Use when asked to check the database, validate schema, optimize indexes, or diagnose Postgres problems. |
| context | fork |
Check database health by running schema and operational checks, then fix any issues found.
All checks are read-only. Fixes are local code changes. Never run database mutations (migrations apply, direct SQL) without explicit user approval.
Always start by checking the dev database — that's where you are and where fixes get verified. Ask the user if they also want to check production. Production is where schema drift and operational health issues matter most, but dev databases drift too (manual SQL, reverted migrations, branch switches).
If checking production, figure out how the user runs commands there (check for Procfiles, Dockerfiles, deploy scripts, etc.) or ask them. Both schema and diagnose need to run against the target database.
uv run plain postgres schema --json
Checks whether the actual database matches what the models expect — drift from failed deploys, manual DDL, partial migrations, or branch switches. Also reports unknown tables (tables in the DB with no corresponding model) which are often left over from uninstalled packages.
uv run plain postgres diagnose --json
Finds unused/duplicate/missing indexes, sequence exhaustion, cache hit ratios, vacuum health, and slow queries. Stats-based checks (unused indexes, cache hit ratios) are most meaningful against production with real traffic. Structural checks (duplicate indexes, missing FK indexes) are valid in any environment.
The JSON output includes suggestion fields for each finding. If findings are on unmanaged tables, check whether those tables should exist at all — schema will have already flagged them as unknown.
Make code and migration changes in the local codebase. For app-owned items, this is typically model changes + uv run plain migrations create. For unknown tables, present uv run plain postgres drop-unknown-tables to the user — it shows what will be dropped and asks for confirmation. Use --yes to skip the prompt if the user wants the agent to run it directly. For other unmanaged items, the suggestions include exact DDL — present these to the user for review, do not run SQL directly.
For structural diagnose findings (duplicate indexes, missing FK indexes): confirm the issue also appears in dev before fixing — you can't verify a fix if you never saw the problem. Run checks before and after the fix, then deploy and re-verify in production.
For schema drift: the drift is environment-specific (prod may have manual DDL that dev doesn't). Verify by confirming your fix makes schema pass cleanly in dev, then deploy and re-verify in production.
Stats-based findings (unused indexes, cache hit ratios) can only be verified in production after deploy.