Db psql
Safe read-only psql wrapper for Claude Code. Provides db.sh with SQL validation hook so database queries are safe and auditable. Configure databases in databases.yaml with env var or keyring backends. TRIGGER when: executing SQL against configured databases. DO NOT TRIGGER when: planning queries (use Dev10x:db), or working with non-database tasks.From its SKILL.md
npx -y skills add Dev10x-Guru/Dev10x-Claude --skill db-psqlAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 8 stars8 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
5.2 KB, as published. Nobody here has run it
PostgreSQL Query Execution
Orchestration
This skill follows references/task-orchestration.md patterns.
Create a task at invocation, mark completed when done:
REQUIRED: Create a task at invocation. Execute at startup:
TaskCreate(subject="Execute safe database query", activeForm="Querying database")
Mark completed when done: TaskUpdate(taskId, status="completed")
Safe read-only psql wrapper with two layers of protection:
- PreToolUse hook (
hooks/scripts/validate-sql.py) — blocks non-SELECT queries before they reach psql - Connection-level safety —
SET default_transaction_read_only = onand read-only DB users / read-replica endpoints
How to Use
${CLAUDE_PLUGIN_ROOT}/skills/db-psql/scripts/db.sh <database> "<SQL>"
${CLAUDE_PLUGIN_ROOT}/skills/db-psql/scripts/db.sh <database> -f <file>
${CLAUDE_PLUGIN_ROOT}/skills/db-psql/scripts/db.sh --list
Common Mistakes (DO NOT do these)
# WRONG — -c flag is not supported, triggers safety hook block
db.sh pp -c "SELECT ..."
# WRONG — stdin piping is not supported
echo "SELECT ..." | db.sh pp
# CORRECT — SQL as second positional argument in quotes
db.sh pp "SELECT ..."
Setup
0. Prerequisites
psql(PostgreSQL client)uv-- Python package manager used byparse-databases.py(pip install uvorbrew install uv)secret-tool(libsecret-tools) -- only needed forkeyringbackend
1. Configure databases
Create databases.yaml in one of the discovered locations. The
db.sh script searches for config files in this order:
$DB_CONFIGenvironment variable (explicit path)- Own skill directory (
skills/db-psql/databases.yaml) ~/.config/Dev10x/databases.yaml(XDG; preferred global location)~/.claude/memory/Dev10x/databases.yaml(deprecated fallback)- Sibling plugin skill directories (
skills/*/databases.yaml) - User skill directories (
~/.claude/skills/*/databases.yaml) - Marketplace plugins (
~/.claude/plugins/marketplaces/*/skills/*/databases.yaml)
Example YAML with both backends:
databases:
my-prod:
label: "My App production (read-only)"
aliases: [mp]
backend: env
env_var: DB_MY_PRODUCTION_RO
my-staging:
label: "My App staging (read-only)"
aliases: [ms]
backend: keyring
keyring_service: claude-db
keyring_account: my-staging
2. Set DSN
Configure the connection string using the backend specified in
databases.yaml:
env backend — set the environment variable in your shell profile:
export DB_MY_PRODUCTION_RO="postgres://user:pass@host:5432/db"
keyring backend — store the DSN in the system keyring:
secret-tool store --label "claude-db my-staging" \
service claude-db account my-staging
3. Safety hook (auto-registered)
The SQL validation hook (validate-sql.py) is automatically
registered via hooks/hooks.json when this plugin is installed.
No manual configuration needed.
Safety Rules
- Read-only queries only — SELECT, WITH (CTEs), EXPLAIN, and SHOW are allowed. The hook rejects INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, TRUNCATE, and other write operations
- Read-only connections — DSNs should use read-only DB users or read-replica endpoints
- 30-second timeout — prevents runaway queries
- Non-SELECT queries: print the raw SQL and tell the user to run it manually. Never attempt workarounds.
When a Query Is Blocked
If the PreToolUse hook blocks a non-SELECT query, tell the user:
This query modifies data and cannot be run through the read-only tool. Here's the SQL to run manually:
-- Run against: <alias> (<label>) <the blocked query>
REQUIRED: Always prefix SQL snippets with a target database comment when outputting SQL for manual execution. This prevents copy-paste errors where SQL intended for staging runs against production. The comment format is:
-- Run against: bs (backend-staging)
Never attempt to bypass the safety checks.
Integration
- Uses
Dev10x:dbfor query planning and schema discovery - Project-specific skills (e.g.,
tt:db) providedatabases.yamlwith aliases and schema references