How do I install the Postgres skill?

Run npx skillmds@latest add lidge-jun/postgres 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 safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Postgres?

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 free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under Apache-2.

Who published Postgres?

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

Postgres by lidge-jun — Agent Skill

Name: Postgres
Author: lidge-jun

Postgres

Execute read-only SQL queries against multiple PostgreSQL databases. Use when: (1) querying PostgreSQL databases, (2) exploring database schemas/tables, (3) running SELECT queries for data analysis, (4) checking database contents. Supports multiple database connections with descriptions for intelligent auto-selection. Blocks all write operations (INSERT, UPDATE, DELETE, DROP, etc.) for safety.

lidge-jun ad3ff39 6 files · 15.7 KB Updated Sep 17, 2026

File contents

PostgreSQL Read-Only Query Skill

Execute safe, read-only queries against configured PostgreSQL databases.

Requirements

Python 3.10+
psycopg2-binary: pip install -r requirements.txt

Tip: For new projects, consider psycopg (v3) (pip install psycopg[binary]) as the recommended modern PostgreSQL adapter. It offers async support, pipeline mode, and better typing. psycopg2 remains supported but is in maintenance mode.

Setup

Create connections.json in the skill directory or ~/.config/claude/postgres-connections.json.

Security: Set file permissions to 600 since it contains credentials:

chmod 600 connections.json

{
  "databases": [
    {
      "name": "production",
      "description": "Main app database - users, orders, transactions",
      "host": "db.example.com",
      "port": 5432,
      "database": "app_prod",
      "user": "readonly_user",
      "password": "your-password",
      "sslmode": "require"
    }
  ]
}

Config Fields

Field	Required	Description
name	Yes	Identifier for the database (case-insensitive)
description	Yes	What data this database contains (used for auto-selection)
host	Yes	Database hostname
port	No	Port number (default: 5432)
database	Yes	Database name
user	Yes	Username
password	Yes	Password
sslmode	No	SSL mode: disable, allow, prefer (default), require, verify-ca, verify-full

Usage

List configured databases

python3 scripts/query.py --list

Query a database

python3 scripts/query.py --db production --query "SELECT * FROM users LIMIT 10"

List tables

python3 scripts/query.py --db production --tables

Show schema

python3 scripts/query.py --db production --schema

Limit results

python3 scripts/query.py --db production --query "SELECT * FROM orders" --limit 100

Database Selection

Match user intent to database description:

User asks about	Look for description containing
users, accounts	users, accounts, customers
orders, sales	orders, transactions, sales
analytics, metrics	analytics, metrics, reports
logs, events	logs, events, audit

If unclear, run --list and ask user which database.

Safety

Read-only mode (readonly=True) + query validation (SELECT/SHOW/EXPLAIN/WITH only)
Single statement per query, 30s timeout, 10K row limit
SSL configurable, credentials sanitized in error output

Troubleshooting

Error	Solution
Config not found	Create `connections.json` in skill directory
Authentication failed	Check username/password in config
Connection timeout	Verify host/port, check firewall/VPN
SSL error	Try `"sslmode": "disable"` for local databases
Permission warning	Run `chmod 600 connections.json`

Workflow

Run --list to show available databases
Match user intent to database description
Run --tables or --schema to explore structure
Execute query with appropriate LIMIT

---name: postgresdescription: Execute read-only SQL queries against multiple PostgreSQL databases. Use when: (1) querying PostgreSQL databases, (2) exploring database schemas/tables, (3) running SELECT queries for data analysis, (4) checking database contents. Supports multiple database connections with descriptions for intelligent auto-selection. Blocks all write operations (INSERT, UPDATE, DELETE, DROP, etc.) for safety.license: Apache-2.0---# PostgreSQL Read-Only Query SkillExecute safe, read-only queries against configured PostgreSQL databases.## Requirements- Python 3.10+- psycopg2-binary: `pip install -r requirements.txt`> **Tip:** For new projects, consider **psycopg (v3)** (`pip install psycopg[binary]`)> as the recommended modern PostgreSQL adapter. It offers async support, pipeline> mode, and better typing. psycopg2 remains supported but is in maintenance mode.## SetupCreate `connections.json` in the skill directory or `~/.config/claude/postgres-connections.json`.**Security**: Set file permissions to `600` since it contains credentials:```bashchmod 600 connections.json``````json{ "databases": [ { "name": "production", "description": "Main app database - users, orders, transactions", "host": "db.example.com", "port": 5432, "database": "app_prod", "user": "readonly_user", "password": "your-password", "sslmode": "require" } ]}```### Config Fields| Field | Required | Description ||-------|----------|-------------|| name | Yes | Identifier for the database (case-insensitive) || description | Yes | What data this database contains (used for auto-selection) || host | Yes | Database hostname || port | No | Port number (default: 5432) || database | Yes | Database name || user | Yes | Username || password | Yes | Password || sslmode | No | SSL mode: disable, allow, prefer (default), require, verify-ca, verify-full |## Usage### List configured databases```bashpython3 scripts/query.py --list```### Query a database```bashpython3 scripts/query.py --db production --query "SELECT * FROM users LIMIT 10"```### List tables```bashpython3 scripts/query.py --db production --tables```### Show schema```bashpython3 scripts/query.py --db production --schema```### Limit results```bashpython3 scripts/query.py --db production --query "SELECT * FROM orders" --limit 100```## Database SelectionMatch user intent to database `description`:| User asks about | Look for description containing ||-----------------|--------------------------------|| users, accounts | users, accounts, customers || orders, sales | orders, transactions, sales || analytics, metrics | analytics, metrics, reports || logs, events | logs, events, audit |If unclear, run `--list` and ask user which database.## Safety- Read-only mode (`readonly=True`) + query validation (SELECT/SHOW/EXPLAIN/WITH only)- Single statement per query, 30s timeout, 10K row limit- SSL configurable, credentials sanitized in error output## Troubleshooting| Error | Solution ||-------|----------|| Config not found | Create `connections.json` in skill directory || Authentication failed | Check username/password in config || Connection timeout | Verify host/port, check firewall/VPN || SSL error | Try `"sslmode": "disable"` for local databases || Permission warning | Run `chmod 600 connections.json` |## Workflow1. Run `--list` to show available databases2. Match user intent to database description3. Run `--tables` or `--schema` to explore structure4. Execute query with appropriate LIMIT

Frequently asked questions