Diagnoses PhoenixKit installation, migration, and runtime issues.

Runs a comprehensive suite of checks covering database connectivity, pool configuration, PgBouncer detection, migration state, lock conflicts, and application configuration. Prints a clear pass/fail report with actionable remediation steps.

Usage

$ mix phoenix_kit.doctor
$ mix phoenix_kit.doctor --prefix=auth
$ mix phoenix_kit.doctor --exit-code

Options

• --prefix - Database schema prefix. When omitted, resolves from config :phoenix_kit, :prefix, then "public" — the same resolution mix phoenix_kit.update / --status use, so a prefixed install is diagnosed against the schema it actually lives in.
• --exit-code - Exit non-zero when any check FAILED. Without it this task prints "N failures" and still exits 0, so a deploy script that runs it cannot act on the result — the same silent success mix phoenix_kit.status --exit-code exists to remove. Warnings never fail the run; they are advisory by construction and several fire on healthy installs. Off by default so deploys that run this purely for its report keep passing.

Checks Performed

1. Repo Detection — Can we find and start the Ecto repo?
2. DB Connectivity — Can we execute a simple query?
3. Pool Configuration — Pool size, checkout timeout, queue settings
4. PgBouncer Detection — Is PgBouncer between app and PostgreSQL?
5. Migration State — PhoenixKit version (COMMENT), schema_migrations alignment
6. Module Schema Versions — Modules owning their own chain, vs what their code expects
7. Schema Drift — Columns a migration should have added but the DB lacks
8. Pending Migrations — Migration files not yet recorded in schema_migrations
9. UUID Column Types — Detects varchar uuid columns that crash Ecto on startup
10. UUID Primary Keys — Detects primary keys that are not the expected uuid type
11. NULL UUIDs in FK Sources — Detects NULL uuids that cause infinite backfill loops
12. Orphaned FK References — Detects orphaned rows behind an existing FK constraint, whether it is already VALID (a trigger-bypassed write, a bulk load, direct catalog surgery) or still NOT VALID (would block its own VALIDATE), and existing constraints still sitting NOT VALID with nothing currently blocking them — V176 validates those in place; this just tells you before it does. Two boundaries on what "checked" means here: discovery reads pg_constraint, so a relationship with no FK constraint declared at all is outside this check's scope and is not examined; and discovery matches both the owning table and the referenced table to the schema being checked (--prefix), so a FK whose referenced table lives in a different schema is outside scope too, even though the owning table itself was checked
13. Schema-Declared Relations Without a DB FK — Every belongs_to PhoenixKit's own Ecto schemas declare, cross-referenced against pg_constraint for a matching foreign key. Reports the COUNT found with no DB-level FK — informational, not a failure: some are intentional (a federated/soft reference cannot carry a FK across an optional module boundary, see V179/V180). This is the complement to check 12's own stated gap above: check 12 only ever sees a relationship that already HAS a declared FK constraint; this one finds relationships Ecto declares that never got one. Derived entirely from what the schema itself declares (owner_key on the belongs_to), never guessed from a column name — so it also cannot see a soft reference that isn't declared as a belongs_to at all (e.g. a plain field, or a polymorphic *_uuid/*_type pair).
14. Lock Conflicts — Any blocked or long-running queries?
15. Orphaned Connections — Idle-in-transaction or stuck connections
16. Oban Configuration — Queues and plugins that consume pool connections
17. Oban Cron Queues — Does every crontab worker have its queue configured?
18. PhoenixKit Supervisor — What's running (update_mode vs full)?
19. Child Start Order — Does the Repo start before PhoenixKit/Oban in application.ex?
20. Update Mode — Is update_mode active?
21. daisyUI Version — Is the host's vendored daisyUI recent enough?
22. User Dashboard (deprecated) — Is the host still on the retired dashboard?
23. Sitemap Discoverability — Is the sitemap actually reachable?
24. Crawler Visibility — noindex on a production-looking host, or a staging-looking host left indexable
25. Demo Auth Pages — Are the demo auth routes still exposed?
26. Manifest Repair (dry-run) — PhoenixKit.Migrations.Repair.verify/1 runs read-only against the generated PhoenixKit.Migrations.ExpectedSchema manifest as an additional, non-fatal check (never :fail). Passes and says so if the manifest has been removed or overridden away in this checkout.
27. Git Hooks — is .githooks/pre-commit enabled via core.hooksPath? Only runs inside a checkout of phoenix_kit itself (.githooks/pre-commit is a phoenix_kit-repo convention, not something installed into a consuming host app) — silently skipped otherwise.