psql-query
The psql-query command executes read-only PostgreSQL analytics queries against development or test databases in Elixir Phoenix projects. Use it to analyze database metrics, user statistics, query performance, and table sizes by running SELECT queries through psql, Mix tasks, or the Tidewave MCP integration when available, while strictly preventing production database access.
mkdir -p ~/.claude/commands && curl -fsSL https://raw.githubusercontent.com/oliver-kriska/claude-elixir-phoenix/HEAD/.claude/commands/psql-query.md -o ~/.claude/commands/psql-query.mdpsql-query.md
# PostgreSQL Analytics
Run analytics queries against the local database using psql or `mix run`.
## Rules
- NEVER run against production
- Use READ-ONLY queries (SELECT only)
- For complex analysis, use `Repo.query/2` in a Mix task
- Format results as ASCII tables or pipe to `column -t`
## Tidewave Integration
If Tidewave MCP is available, prefer it over psql/mix run:
- `mcp__tidewave__execute_sql_query` for direct SQL queries
- `mcp__tidewave__project_eval` for Ecto-based queries via `Repo.query!/2` or `Repo.all/1`
Fall back to psql/mix run only if Tidewave is not detected.
## Workflow
1. Check if Tidewave MCP is available — if yes, use `mcp__tidewave__execute_sql_query`
2. Otherwise, detect database URL from `config/dev.exs` or `DATABASE_URL`
3. Run query via: `psql $DATABASE_URL -c "YOUR QUERY" --expanded`
4. For Ecto: `mix run -e 'MyApp.Repo.query!("SELECT ...") |> IO.inspect()'`
5. Summarize results
## Example prompts
- "How many users signed up this week?"
- "Show me the slowest queries from pg_stat_statements"
- "What's the table size distribution?"
- "Show index usage stats"Ash Framework — resources, actions, policies, aggregates, calculations,
Compatibility alias for the Elixir/Phoenix plugin's LiveView assigns audit. Invoke explicitly with /lv:assigns.
Inspect LiveView socket assigns for memory bloat — missing temporary_assigns, unused assigns, unbounded lists needing streams, memory estimates. Use when LiveView memory grows or you need to add temporary_assigns.
Project health audit and health check — architecture, performance, tests, dependencies, code quality. Use when assessing overall project health, before releases, or after refactors.
Analyze Phoenix context boundaries and module coupling via mix xref. Use when checking cross-context calls, validating dependencies, before splitting modules, or reviewing architecture.
Brainstorm Elixir/Phoenix features — explore ideas, compare approaches, gather requirements. Use when vague idea, not sure how to approach, or want to discuss before plan.
Interactive briefing of a plan file — explains reasoning, schema decisions, component choices. Use when developers need to understand a plan before approving.
Summarize and review what changed while you were away. Use after a weekend, vacation, or flight to check missed PRs, git commits, Linear tickets, and meetings — one prioritized brief, not a firehose.