Execute read-only SQL queries to explore schemas, analyze data, and check contents across multiple PostgreSQL databases.
- GitHub stars
- 454
- Files
- 6
- Last commit
- Nov 2, 2026
- License
- Apache-2.0
- Allowed tools
- —
What does the postgres skill do?
postgres is an agent skill. Execute read-only SQL queries to explore schemas, analyze data, and check contents across multiple PostgreSQL databases.
Summary generated from the skill's SKILL.md.
About the postgres skill
Analyzing database schemas and inspecting data contents across multiple PostgreSQL instances is what this skill enables. Developers and data analysts use it to run SELECT queries, explore table structures, and perform data analysis without the risk of modifying any records. An agent should load this tool when a user needs to investigate specific database records, verify table schemas, or pull metrics from configured databases.
The skill relies on a connections.json file containing host, port, and credential information. It provides specialized commands to list tables, show schemas, and execute queries with built-in safety limits. To prevent accidental data loss, the tool blocks all write operations like INSERT or DELETE and enforces a read-only session. It also includes protections such as a 30-second statement timeout, a 10,000 row limit per query, and a 100 character cap per column to ensure stable performance.
What an agent can do with it
- 1Explore database structuresAn agent can retrieve a list of all tables or the specific schema of a database to understand its organization.
- 2Perform data analysisA developer can execute SELECT queries to pull specific datasets for reporting or investigation.
- 3Identify correct database connectionsThe skill helps an agent select the right database by matching user requests to database descriptions.
- 4Safely inspect production dataUsers can query live databases knowing that all write operations are strictly blocked.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the postgres skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the postgres skill in Plugin
/plugin marketplace add sanjay3290/ai-skills /plugin install ai-skills@ai-skills
Install the postgres skill in Claude Code
~/.claude/skills/postgres/SKILL.md
$ npx degit sanjay3290/ai-skills/skills/postgres ~/.claude/skills/postgresInstall the postgres skill in Claude Code (project)
.claude/skills/postgres/SKILL.md
$ npx degit sanjay3290/ai-skills/skills/postgres .claude/skills/postgresInstall the postgres skill in Codex
~/.agents/skills/postgres/SKILL.md
$ npx degit sanjay3290/ai-skills/skills/postgres ~/.agents/skills/postgresInstall the postgres skill in Gemini CLI
~/.gemini/skills/postgres/SKILL.md
$ npx degit sanjay3290/ai-skills/skills/postgres ~/.gemini/skills/postgresInstall the postgres skill in Claude.ai
npx degit sanjay3290/ai-skills/skills/postgres postgres && zip -r postgres.zip postgres # claude.ai → Customize → Skills → + → Create skill → Upload a skill → postgres.zip
Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the scripts before you let an agent run them. How checks work
- Source repository linked and reachablesanjay3290/ai-skills/skills/postgres is public and reachablegithub.com/sanjay3290/ai-skills/tree/HEAD/skills/postgres ↗Pass
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit 2026-11-02github.com/sanjay3290/ai-skills/commits ↗Pass
- No download-and-run or credential theft in scripts1 script read; no download-and-run, remote eval, base64 execution or credential uploadPass
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/sanjay3290/ai-skills/blob/HEAD/skills/postgres/SK ↗Pass
- Pre-approved tools are scopedNo pre-approved tools; the agent asks before using onegithub.com/sanjay3290/ai-skills/blob/HEAD/skills/postgres/SK ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 130 linesgithub.com/sanjay3290/ai-skills/blob/HEAD/skills/postgres/SK ↗Pass
SKILL.md
View on GitHubPostgreSQL Read-Only Query Skill
Execute safe, read-only queries against configured PostgreSQL databases.
Requirements
- Python 3.8+
- psycopg2-binary:
pip install -r requirements.txt
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 Features
- Read-only session: Connection uses PostgreSQL
readonly=Truemode (primary protection) - Query validation: Only SELECT, SHOW, EXPLAIN, WITH queries allowed
- Single statement: Multiple statements per query rejected
- SSL support: Configurable SSL mode for encrypted connections
- Query timeout: 30-second statement timeout enforced
- Memory protection: Max 10,000 rows per query to prevent OOM
- Column width cap: 100 char max per column for readable output
- Credential sanitization: Error messages don't leak passwords
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 |
Exit Codes
- 0: Success
- 1: Error (config missing, auth failed, invalid query, database error)
Workflow
- Run
--listto show available databases - Match user intent to database description
- Run
--tablesor--schemato explore structure - Execute query with appropriate LIMIT
Files in this skill
6postgres skill questions
How do I install the postgres skill in Claude Code?
Run npx degit sanjay3290/ai-skills/skills/postgres ~/.claude/skills/postgres. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the postgres skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
Is it safe to run write operations with this skill?
No, the skill is designed for safety by blocking all write operations like INSERT, UPDATE, DELETE, and DROP, and only allowing SELECT, SHOW, EXPLAIN, and WITH queries.
How does the skill select the correct database?
The skill matches user intent to the database description provided in the configuration file.
How should I secure my database credentials?
You should set file permissions to 600 for your connections.json file since it contains sensitive credentials.