postgres-query · civitai, event-engine — Claude Code skill: what it does, how to install
postgres-query runs PostgreSQL queries, inspects index usage, and analyzes execution plans using read-only connections by default.
Apache-2.0 ★ 7,327 updated 2026-10-25
npx skills add civitai/civitai --skill postgres-query -a claude-codeWhat postgres-query does
This skill provides a helper script at node .claude/skills/postgres-query/query.mjs for database debugging and query profiling. Connections default to a read replica via DATABASE_REPLICA_URL, which prevents accidental data modifications by blocking INSERT, UPDATE, DELETE, and DROP commands.
Modifying data requires the --writable flag, which targets the primary database. The agent must obtain explicit user confirmation before applying this flag. For query optimization, the --explain flag triggers EXPLAIN ANALYZE to reveal missing indexes and sequential scans. Other options include reading queries from files with -f, setting timeouts via -t (30 seconds default), and formatting output as JSON.
Execution requires Node.js and configured database environment variables in your workspace.
What it helps with
- run EXPLAIN ANALYZE to verify index scans on PostgreSQL tables
- execute read-only queries against database replicas without write risks
- compare execution times between two alternative SQL query structures
- export query output directly to JSON for automated processing
Example prompts for the agent
- Run EXPLAIN on SELECT * FROM "User" WHERE id = 10
- Execute the query in analytics.sql with a 60 second timeout
- Compare performance between these two SQL queries and dump results to JSON
How to install postgres-query
1Skills CLI (Vercel)
npx skills add civitai/civitai --skill postgres-query -a claude-code2Manually: put the files in place
~/.claude/skills/postgres-query/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/postgres-query/
1Skills CLI (Vercel)
npx skills add civitai/civitai --skill postgres-query -a codex2Manually: put the files in place
.agents/skills/postgres-query/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add civitai/civitai --skill postgres-query -a cursor2Manually: put the files in place
.cursor/skills/postgres-query/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install civitai/civitai apps/event-engine/.claude/skills/postgres-query2Manually: put the files in place
.github/skills/postgres-query/SKILL.md1Skills CLI (Vercel)
npx skills add civitai/civitai --skill postgres-query -a gemini-cli2Platform CLI
gemini skills install https://github.com/civitai/civitai --path apps/event-engine/.claude/skills/postgres-queryManually: put the files in place
.devin/skills/postgres-query/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add civitai/civitai --skill postgres-query -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about postgres-query
How to install postgres-query in Claude Code?
Run npx skills add civitai/civitai --skill postgres-query -a claude-code in your terminal.
What does postgres-query do?
It runs ad-hoc PostgreSQL queries, generates EXPLAIN ANALYZE performance plans, and checks whether queries utilize database indexes properly.
How does write protection work in postgres-query?
It routes traffic to DATABASE_REPLICA_URL by default and halts write statements unless invoked with --writable and explicit user permission.
Source text
SKILL.md · Apache-2.0
--- name: postgres-query description: 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. --- # PostgreSQL Query Testing Use this skill to run ad-hoc PostgreSQL queries for testing, debugging, and performance analysis. ## Running Queries Use the included query script: ```bash node .claude/skills/postgres-query/query.mjs "SELECT * FROM \"User\" LIMIT 5" ``` ### Options | Flag | Description | |------|-------------| | `--explain` | Run EXPLAIN ANALYZE on the query | | `--writable` | Use primary database instead of read replica (requires user permission) | | `--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 | ### Examples ```bash # 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" ``` ## Safety Features 1. **Read-only by default**: Uses `DATABASE_REPLICA_URL` to prevent accidental writes 2. **Write protection**: Blocks INSERT/UPDATE/DELETE/DROP unless `--writable` flag is used 3. **Explicit permission required**: Before using `--writable`, you MUST ask the user for permission ## When to Use --writable Only use the `--writable` flag when: - The user explicitly requests write access - You need to test write operations - You're verifying transaction behavior **IMPORTANT**: Always ask the user for permission before running with `--writable`. ## Comparing Query Performance To compare two query approaches: ```bash # 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 ``` ## Verifying Index Usage Run with `--explain` and look for: - **Good**: "Index Scan", "Bitmap Index Scan", "Index Only Scan" - **Bad**: "Seq Scan" on large tables (indicates missing or unused index) ```bash node .claude/skills/postgres-query/query.mjs --explain "SELECT * FROM \"Account\" WHERE provider = 'discord'" ```
© civitai · Apache-2.0 · civitai/civitai
Similar skills
All skills for Data and databases →postgres-query by other authors comes first.