db

DB — Universal Database Access

Reads connection config from the project instruction file (CLAUDE.md, AGENTS.md, .cursorrules, or equivalent) or ~/.claude/db-connections.json (global registry).

Scope: /db executes specific SQL or migrations against named connections. For analytics in plain English, use /query.

Supported engines

cloud-sql | postgres | snowflake | databricks | athena | presto | oracle

Usage

• /db — default audit query for current project DB
• /db "SELECT count(*) FROM users" — arbitrary SQL on current project DB
• /db migrate — run pending migrations
• /db prod-snowflake — named connection from global registry
• /db prod-snowflake "SELECT ..." — named connection + custom SQL

---

Step 0 — Parse arguments

# If first arg looks like a connection name (no spaces, no SQL keywords), treat as named connection
ARGS="${1:-}"
if echo "$ARGS" | grep -qE '^[a-zA-Z0-9_-]+$' && ! echo "$ARGS" | grep -qiE '^(SELECT|INSERT|UPDATE|DELETE|CREATE|DROP|ALTER|SHOW|DESCRIBE|migrate)'; then
  NAMED_CONNECTION=$(echo "$ARGS" | awk '{print $1}')
  SQL=$(echo "$ARGS" | cut -s -d' ' -f2-)
else
  NAMED_CONNECTION=""
  SQL="$ARGS"
fi

---

Step 1 — Load connection config

# Detect project instruction file
INSTRUCTION_FILE=$(ROOT=$(git rev-parse --show-toplevel 2>/dev/null); for f in CLAUDE.md AGENTS.md .cursorrules; do [ -f "$ROOT/$f" ] && echo "$ROOT/$f" && break; done)
DB_CONNECTIONS="$HOME/.claude/db-connections.json"

if [ -n "$NAMED_CONNECTION" ]; then
  ENGINE=$(python3 -c "import json; d=json.load(open('$DB_CONNECTIONS')); c=d.get('$NAMED_CONNECTION',{}); print(c.get('engine',''))" 2>/dev/null)
  CONFIG_SOURCE="registry:$NAMED_CONNECTION"

elif [ -n "$INSTRUCTION_FILE" ] && grep -q "^engine:" "$INSTRUCTION_FILE" 2>/dev/null; then
  ENGINE=$(grep "^engine:" "$INSTRUCTION_FILE" | head -1 | cut -d: -f2 | tr -d ' ')
  CONNECTION_NAME=$(grep "^connection:" "$INSTRUCTION_FILE" | head -1 | cut -d: -f2 | tr -d ' ')
  CONFIG_SOURCE="instruction-file"

elif [ -f "$DB_CONNECTIONS" ]; then
  echo "No DB config found in project instruction file. Available connections:"
  python3 -c "
import json
d = json.load(open('$DB_CONNECTIONS'))
for i, (name, cfg) in enumerate(d.items(), 1):
    print(f'  {i}) {name} ({cfg.get(\"engine\",\"unknown\")})')
"
  read -rp "Select connection (number or name): " SELECTION
  NAMED_CONNECTION=$(python3 -c "
import json, sys
d = json.load(open('$DB_CONNECTIONS'))
keys = list(d.keys())
sel = '$SELECTION'
if sel.isdigit() and 1 <= int(sel) <= len(keys):
    print(keys[int(sel)-1])
elif sel in d:
    print(sel)
else:
    print('', end='')
" 2>/dev/null)
  ENGINE=$(python3 -c "import json; d=json.load(open('$DB_CONNECTIONS')); print(d.get('$NAMED_CONNECTION',{}).get('engine',''))" 2>/dev/null)
  CONFIG_SOURCE="registry:$NAMED_CONNECTION"

else
  echo "ERROR: No database config found."
  echo "  Option 1: Add a '## Database' section to your project instruction file"
  echo "  Option 2: Create ~/.claude/db-connections.json with named connections"
  exit 1
fi

if [ -z "$ENGINE" ]; then
  echo "ERROR: Could not determine database engine from config."
  exit 1
fi

echo "Engine: $ENGINE | Config: $CONFIG_SOURCE"