How do I install the Postgres Query skill?

Run npx skillmds@latest add tomevault-io/postgres-query in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Postgres Query safe to use?

This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Postgres Query?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Postgres Query free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Postgres Query?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Postgres Query by tomevault-io — Agent Skill

Name: Postgres Query
Author: tomevault-io

Postgres Query

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 when this capability is needed.

tomevault-io Updated Sep 17, 2026

File contents

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:

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

# 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

Read-only by default: Uses DATABASE_REPLICA_URL to prevent accidental writes
Write protection: Blocks INSERT/UPDATE/DELETE/DROP unless --writable flag is used
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:

# 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)

node .claude/skills/postgres-query/query.mjs --explain "SELECT * FROM \"Account\" WHERE provider = 'discord'"

Converted and distributed by TomeVault — claim your Tome and manage your conversions.

---name: postgres-querydescription: 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 when this capability is needed.---# PostgreSQL Query TestingUse this skill to run ad-hoc PostgreSQL queries for testing, debugging, and performance analysis.## Running QueriesUse the included query script:```bashnode .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 querynode .claude/skills/postgres-query/query.mjs "SELECT id, username FROM \"User\" LIMIT 5"# Check query performancenode .claude/skills/postgres-query/query.mjs --explain "SELECT * FROM \"Model\" WHERE id = 1"# Override default 30s timeout for longer queriesnode .claude/skills/postgres-query/query.mjs --timeout 60 "SELECT ... (complex query)"# Query from filenode .claude/skills/postgres-query/query.mjs -f my-query.sql# JSON output for processingnode .claude/skills/postgres-query/query.mjs --json "SELECT id, username FROM \"User\" LIMIT 3"```## Safety Features1. **Read-only by default**: Uses `DATABASE_REPLICA_URL` to prevent accidental writes2. **Write protection**: Blocks INSERT/UPDATE/DELETE/DROP unless `--writable` flag is used3. **Explicit permission required**: Before using `--writable`, you MUST ask the user for permission## When to Use --writableOnly 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 PerformanceTo compare two query approaches:```bash# Run first approachnode .claude/skills/postgres-query/query.mjs --explain "SELECT ... (approach 1)"# Run second approachnode .claude/skills/postgres-query/query.mjs --explain "SELECT ... (approach 2)"# Compare actual resultsnode .claude/skills/postgres-query/query.mjs --json "SELECT ... (approach 1)" > /tmp/q1.jsonnode .claude/skills/postgres-query/query.mjs --json "SELECT ... (approach 2)" > /tmp/q2.json```## Verifying Index UsageRun 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)```bashnode .claude/skills/postgres-query/query.mjs --explain "SELECT * FROM \"Account\" WHERE provider = 'discord'"```---> Converted and distributed by [TomeVault](https://tomevault.io/claim/civitai) — claim your Tome and manage your conversions.

Frequently asked questions