db-redis

Inspect Redis instances declared in .env. Same numbered block pattern as every other db-* and SOCIAL_*_N_* integration.

Setup — one-time, per instance

Add a block to .env (gitignored):

env
DB_REDIS_1_LABEL=cache-dev
DB_REDIS_1_HOST=redis.dev.internal
DB_REDIS_1_PORT=6379
DB_REDIS_1_DB=0                        # numeric DB index (default 0)
# DB_REDIS_1_USERNAME=                 # optional (Redis 6+ ACL)
DB_REDIS_1_PASSWORD=...
# DB_REDIS_1_TLS=false                 # default false
# DB_REDIS_1_ALLOW_WRITE=false         # default false (no write verbs in v1 anyway)
# DB_REDIS_1_QUERY_TIMEOUT=30
# DB_REDIS_1_MAX_ROWS=1000

Full URL alternative (wins when both are set):

env
DB_REDIS_2_LABEL=queue-prod
DB_REDIS_2_URL=rediss://user:pw@host:6380/0

LABEL is always required.

Usage

All commands output JSON on stdout (safe to pipe). Errors go to stderr.

List configured connections

bash
python3 .claude/skills/db-redis/scripts/db_client.py accounts

Health-check (PING, reports RTT)

bash
python3 .claude/skills/db-redis/scripts/db_client.py test cache-dev

List keys (production-safe — uses SCAN, never KEYS )

bash
# All keys (up to MAX_ROWS)
python3 .claude/skills/db-redis/scripts/db_client.py keys cache-dev

# Pattern + limit
python3 .claude/skills/db-redis/scripts/db_client.py keys cache-dev 'user:*' 50

Read a single key (auto-detects type)

bash
python3 .claude/skills/db-redis/scripts/db_client.py get cache-dev user:123

Handles string, list, set, hash, zset, stream automatically. Includes TTL in seconds (null if persistent).

Server info

bash
# All sections
python3 .claude/skills/db-redis/scripts/db_client.py info cache-dev

# Specific section (memory, clients, replication, stats, persistence, ...)
python3 .claude/skills/db-redis/scripts/db_client.py info cache-dev memory

Database size (number of keys)

bash
python3 .claude/skills/db-redis/scripts/db_client.py dbsize cache-dev

Output shape

get on a string key:

json
{
  "ok": true,
  "label": "cache-dev",
  "key": "user:123",
  "type": "string",
  "value": "alice",
  "ttl_seconds": 3600
}

keys:

json
{
  "ok": true,
  "query_id": "uuid-v4",
  "label": "cache-dev",
  "pattern": "user:*",
  "keys": ["user:1", "user:2", "user:3"],
  "row_count": 3,
  "truncated": false,
  "execution_time_ms": 8
}

Guardrails

• Read-only verbs only in v1 — GET, SCAN (via keys), TYPE, TTL, LRANGE/SMEMBERS/HGETALL/ZRANGE/XRANGE (via get), INFO, DBSIZE, PING. No SET/DEL/FLUSHDB/FLUSHALL exposed. ALLOW_WRITE reserved for future write commands.
• SCAN instead of KEYS — keys uses scan_iter with count=200 to avoid blocking the server on production instances.
• Result cap — keys stops at MAX_ROWS. Collection readers (LRANGE/SMEMBERS/ZRANGE/XRANGE inside get) also cap at MAX_ROWS.
• Decoding — responses decoded as UTF-8 (decode_responses=True). Raw bytes not supported in v1; if you need binary values, store them base64-encoded or ask for a follow-up.

Error codes

• no_connections, not_found, ambiguous, config_error, usage — same as other db-* skills
• driver_missing — redis (python) not installed
• connection_failed — network, auth, TLS, or timeout
• invalid_args — bad limit argument

Workflow

1. accounts to confirm the label.
2. dbsize or info memory for a quick overview before listing.
3. keys <label> '<pattern>' to find what you're looking for — always use a narrow pattern on prod instances.
4. get <label> <key> to read individual values. TTL is included so you know if the value is ephemeral.

Dependencies

• Python 3.10+
• redis (python client) — not pre-installed; uv pip install redis on first use. Works against Redis 5+, Redis Stack, Valkey, and managed services (Upstash, Redis Cloud, AWS ElastiCache, Google Memorystore).

Deep-dive references

Redis isn't covered by PlanetScale's database-skills. Authoritative sources:

• Redis Commands
• SCAN vs KEYS — why keys uses SCAN
• ACL (Access Control List) — Redis 6+ username/password
• Memory Optimization
• Persistence (RDB vs AOF)