PostgreSQL Database

Overview

PostgreSQL Database is the postgres skill from sanjay3290/ai-skills, a collection of portable Agent Skills that work in Claude Code, Gemini CLI, Cursor, Codex CLI, Goose, and other clients that follow the Agent Skills standard. It lets an agent run read-only SQL against one or more configured PostgreSQL databases through a small Python script, so you can ask questions about your data in plain language without giving the agent write access.

Key Features

• Multiple connections with descriptions. Each database in connections.json has a description field ("users, orders, transactions"). The agent matches your question to that text to pick the right database, and runs --list and asks you when intent is unclear.
• Defense in depth. The session is opened in PostgreSQL readonly=True mode, and queries are also validated: only SELECT, SHOW, EXPLAIN, and WITH are allowed, and multiple statements in one call are rejected.
• Guard rails. A 30-second statement timeout, a 10,000-row cap per query, a 100-character column width cap, and error messages that do not echo credentials.
• Configurable SSL via sslmode (disable through verify-full).

Quick Start

1. Install the collection. In Claude Code: /plugin marketplace add sanjay3290/ai-skills, then /plugin install ai-skills@ai-skills.
2. Install the Python dependency: pip install -r requirements.txt (psycopg2-binary, Python 3.8+).
3. Create connections.json in the skill folder or at ~/.config/claude/postgres-connections.json, then chmod 600 it because it holds passwords.
4. Ask the agent, or call the script directly:

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

Use Cases

• Exploring an unfamiliar schema before writing a migration or feature.
• Answering ad hoc analytics questions against a replica.
• Checking what data exists while debugging, without leaving the terminal.

Limitations

• Credentials sit in a plain JSON file; use a dedicated read-only database user and restrict file permissions.
• Only PostgreSQL. The same repository ships separate mysql and mssql skills.
• Read-only by design, so it cannot run migrations or fix data.

FAQ

Can the agent modify my data with this skill?

No. The connection is opened read-only and the script rejects anything other than SELECT, SHOW, EXPLAIN, and WITH statements.

Where does the skill look for connection settings?

In connections.json inside the skill directory, or in ~/.config/claude/postgres-connections.json.

Alternatives

• Supabase and Neon are hosted Postgres platforms with their own agent tooling.
• MySQL if your data lives in MySQL instead; the same repository offers a matching mysql skill.

Source: postgres skill on GitHub. More in Skills and the database tag.