Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add civitai/civitai --skill postgres-query -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/postgres-query/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/postgres-query/

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.

postgres-query civitai postgres-query — a skill for Claude Code that executes PostgreSQL queries during debugging and performance analysis. It targets specific database environments with --prod or --dev flags under read-only mode. CX Codex +1 105installs postgres-tuning oakoss postgres-tuning — a skill for Claude Code, Codex, Cursor and other agents that provides PostgreSQL 17/18+ performance tuning guidance. Covers async I/O, query plan forensics, index strategy, autovacuum, pgvector, and connection pooling. CX Codex +1 136installs postgres-expert 0xfurai postgres-expert helps design PostgreSQL schemas, optimize slow SQL queries, and configure indexes for balanced read and write performance. CX Codex ★ 1,029repo stars neon-postgres neondatabase neon-postgres is a Claude Code skill for working with Neon databases, from connections and schemas to branches. It activates for existing database, SQL, inspection, and search tasks. CX Codex +1 315,000installs postgres-patterns affaan-m postgres-patterns is a Claude Code skill for PostgreSQL schema design and query tuning, covering indexes, data types, RLS policies, and slow-query diagnosis. CX Codex +1 7,200installs postgres-best-practices neondatabase postgres-best-practices is a Claude Code skill for PostgreSQL schema design, SQL, and query tuning. It activates for database setup, migrations, and troubleshooting slow queries. CX Codex +1 2,100installs design-postgres-tables tigerdata design-postgres-tables — a reference skill for PostgreSQL table design: data types, indexes, constraints, JSONB and partitioning. Useful when your agent writes or edits a schema. CX Codex +1 680installs

From the same set11

The whole set →
quick-mockups quick-mockups generates 3 to 5 parallel UI mockups in HTML. Useful when you need to explore layouts, wireframes, and hierarchy variations before writing frontend code. CX Codex +1 1,700installs meilisearch-admin meilisearch-admin — a skill for monitoring Meilisearch: check indexes, tasks, server health, and search settings. Spot indexing errors and diagnose what's wrong with your search. CX Codex +1 132installs postgres-query postgres-query — a skill for Claude Code that executes PostgreSQL queries during debugging and performance analysis. It targets specific database environments with --prod or --dev flags under read-only mode. CX Codex +1 105installs agent-review Route code and prompts to external AI agents for review. Anthropic models use your local subscription via Claude Agent SDK; other models go through OpenRouter API. Useful for security audits, architecture validation, or a second opinion. CX Codex +1 3installs discord Posts messages, embeds, and announcements to Discord channels via REST API. Useful for team alerts and release notices during coding sessions. CX Codex +1 ★ 7,327repo stars clickhouse-query clickhouse-query runs ad-hoc ClickHouse queries from the chat: metrics, event data, execution plans. Read-only unless you say otherwise. CX Codex +1 ★ 7,327repo stars redis-inspect redis-inspect — a skill that reads keys, values and TTLs across two Redis instances, the main cache and the system cache. Handy when you need to see what the cache holds right now. CX Codex +1 ★ 7,327repo stars browser-automation browser-automation runs browser sessions behind an HTTP server, keeps auth profiles, and supports concurrent users. Useful for repeatable flows and multi-user checks. CX Codex +1 ★ 7,327repo stars

Project sponsors

Companies that keep this analytics open