Run PostgreSQL queries for testing, debugging, and performance analysis. Use when you need to query the database directly, run EXPLAIN ANALYZE, compare query results, or test SQL optimizations. Always uses read-only connections unless explicitly directed otherwise.
Use this skill to run ad-hoc PostgreSQL queries for testing, debugging, and performance analysis.
Use the included query script:
node .claude/skills/postgres-query/query.mjs "SELECT * FROM \"User\" LIMIT 5"
| Flag | Description |
|---|---|
--explain | Run EXPLAIN ANALYZE on the query |
--writable | Use primary database instead of read replica (requires user permission) |
--data-packet | Use the DataPacket replica (DATABASE_DATA_PACKET_URL) — read-only |
--timeout <s>, -t |
| Query timeout in seconds (default: 30) |
--file, -f | Read query from a file |
--json | Output results as JSON |
--quiet, -q | Minimal output, only results |
# Simple query
node .claude/skills/postgres-query/query.mjs "SELECT id, username FROM \"User\" LIMIT 5"
# Check query performance
node .claude/skills/postgres-query/query.mjs --explain "SELECT * FROM \"Model\" WHERE id = 1"
# Override default 30s timeout for longer queries
node .claude/skills/postgres-query/query.mjs --timeout 60 "SELECT ... (complex query)"
# Query from file
node .claude/skills/postgres-query/query.mjs -f my-query.sql
# JSON output for processing
node .claude/skills/postgres-query/query.mjs --json "SELECT id, username FROM \"User\" LIMIT 3"
| Flag | Connection string | Use when |
|---|---|---|
| (default) | DATABASE_REPLICA_URL (falls back to DATABASE_URL) | Most queries — read-only main replica |
--writable | DATABASE_URL | Writes against primary; needs user permission |
--data-packet | DATABASE_DATA_PACKET_URL | Querying the DataPacket replica (read-only) |
DATABASE_REPLICA_URL to prevent accidental writes--writable flag is used--writable, you MUST ask the user for permissionOnly use the --writable flag when:
IMPORTANT: Always ask the user for permission before running with --writable.
To compare two query approaches:
# Run first approach
node .claude/skills/postgres-query/query.mjs --explain "SELECT ... (approach 1)"
# Run second approach
node .claude/skills/postgres-query/query.mjs --explain "SELECT ... (approach 2)"
# Compare actual results
node .claude/skills/postgres-query/query.mjs --json "SELECT ... (approach 1)" > /tmp/q1.json
node .claude/skills/postgres-query/query.mjs --json "SELECT ... (approach 2)" > /tmp/q2.json
Run with --explain and look for:
node .claude/skills/postgres-query/query.mjs --explain "SELECT * FROM \"Account\" WHERE provider = 'discord'"