Query PostgreSQL databases with read-only safety guarantees

Executes safe, read-only queries against configured PostgreSQL databases, exploring schemas, tables, and data across multiple configured connections with defense-in-depth protection against accidental INSERT/UPDATE/DELETE or DDL.

Reach for it any time a query needs to run against a real database but the person or agent running it shouldn't be able to change anything, intentionally or not. Its own protections are explicitly secondary, not primary: they reduce accidental writes but cannot override database-server policy, triggers, extensions, or an over-privileged account, so a database role with genuinely read-only permissions still has to be the real control. Query results can contain personal, confidential, or regulated data - confirm the intended database and avoid exporting or sharing results without explicit authorization. The script is not a replacement for backups, auditing, access reviews, or production change controls.

Requires Python 3.8+ and psycopg2-binary (pip install -r requirements.txt). Setup creates a connections.json file in the skill directory or ~/.config/claude/postgres-connections.json, permissioned to 600 since it holds credentials:

chmod 600 connections.json

with database entries shaped like:

{
  "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"
    }
  ]
}

Required fields are name, description, host, database, user, and password; port defaults to 5432 and sslmode defaults to prefer (options: disable, allow, prefer, require, verify-ca, verify-full). Usage runs through scripts/query.py: --list shows configured databases, --db <name> --query "<SQL>" runs a query, --db <name> --tables lists tables, --db <name> --schema shows the schema, and --limit <n> caps result rows. Exit codes are 0 for success and 1 for any error (missing config, failed auth, invalid query, database error).

Database selection matches user intent to each connection's description field - questions about users or accounts look for descriptions mentioning users/accounts/customers, orders or sales look for orders/transactions/sales, analytics or metrics look for analytics/metrics/reports, and logs or events look for logs/events/audit; if it's unclear, run --list and ask the user which database to use. Layered safety features: the connection itself runs in PostgreSQL readonly=True mode as the primary protection, query validation only allows SELECT/SHOW/EXPLAIN/WITH statements, multiple statements per query are rejected, SSL mode is configurable for encrypted connections, a 30-second statement timeout is enforced, results are capped at 10,000 rows to prevent out-of-memory errors, columns are capped at 100 characters for readable output, and error messages are sanitized so they never leak passwords. Common troubleshooting: a missing config means creating connections.json in the skill directory; authentication failures mean checking the username/password; connection timeouts mean verifying host/port and firewall/VPN; SSL errors on a local database can be worked around with "sslmode": "disable"; and a permission warning means running chmod 600 connections.json again. The intended workflow: run --list to see available databases, match user intent to a database description, run --tables or --schema to explore structure, then execute the query with an appropriate --limit.

Someone juggling several databases on file at once, where naming the right one by hand every time would get tedious - the description field on each connection entry does that matching automatically, and error messages are scrubbed of credentials before they ever reach the screen.