Execute read-only SQL queries against PostgreSQL databases. Use when: (1) querying PostgreSQL data, (2) exploring schemas/tables, (3) running SELECT queries for analysis, (4) checking database contents. Supports multiple database connections with descriptions for auto-selection. Blocks all write operations (INSERT, UPDATE, DELETE, DROP, etc.) for safety.
Execute safe, read-only queries against configured PostgreSQL databases.
pip install -r requirements.txtCreate connections.json in the skill directory or ~/.config/claude/read-only-postgres-connections.json.
Security: Set file permissions to 600 since it contains credentials:
chmod 600 connections.json
{
"databases": [
{
"name": "app-db-dev",
"description": "Primary app database (public schema: users, organizations, orders, order_items, events)",
"host": "localhost",
"port": 5432,
"database": "app_dev",
"user": "app_user",
"password": "app_password",
"sslmode": "disable"
},
{
"name": "app-db-staging",
"description": "Staging database (same schema as primary app)",
"host": "localhost",
"port": 5432,
"database": "app_staging",
"user": "app_user",
"password": "app_password",
"sslmode": "disable"
}
]
}
| 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 |
| pii_masking | No | Object mapping table names to arrays of column names to mask |
Mask sensitive data in query results by adding a pii_masking field to any database config. Middle characters are replaced with *, keeping only the first and last characters visible.
{
"name": "app-db-dev",
"host": "localhost",
"database": "app_dev",
"user": "readonly",
"password": "secret",
"pii_masking": {
"users": ["email", "phone", "first_name", "last_name"],
"orders": ["shipping_address"]
}
}
How it works:
[email protected] → j************m555-1234 → 5******4Jo → Jo (2 chars or fewer are not masked)Masking is applied automatically when querying a matching table. A footer note indicates which columns were masked.
python3 scripts/query.py --list
python3 scripts/query.py --db app-db-dev --query "SELECT id, email, created_at FROM users LIMIT 10"
python3 scripts/query.py --db app-db-dev --tables
python3 scripts/query.py --db app-db-dev --schema
python3 scripts/query.py --db app-db-dev --query "SELECT id, status, total_amount FROM orders" --limit 100
Match user intent to database description:
| User asks about | Look for description containing |
|---|---|
| users, accounts | users, accounts |
| organizations, teams | organizations, teams |
| orders, payments | orders, payments |
| events, audit logs | events, audit, logs |
| analytics or reporting | analytics, reporting |
| background jobs or queues | jobs, queue, outbox |
If unclear, run --list and ask user which database.
readonly=True mode (primary protection)| 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 |
--list to show available databases--tables or --schema to explore structure