/db-redis

name: db-redis
description: "Inspect Redis instances configured in .env (DB_REDIS_N_*). Use when the user asks to read keys, check cache state, list keys by pattern, or query info/dbsize on a Redis server. Picks connection by label (e.g. 'cache-dev', 'queue-prod') or numeric index. Read-only in v1 — no SET/DEL/FLUSH exposed."
metadata:
  openclaw:
    requires:
      env:
        - DB_REDIS_1_LABEL
      bins:
        - python3
    primaryEnv: DB_REDIS_1_LABEL
    files:
      - "scripts/*"
      - "references/*"

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):

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):

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

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

Health-check (PING, reports RTT)

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

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

# 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)

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

# 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)

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

Output shape

`get` on a string key:

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

`keys`:

{
  "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](https://redis.io/commands/)
• [SCAN vs KEYS](https://redis.io/docs/latest/commands/scan/) — why `keys` uses SCAN
• [ACL (Access Control List)](https://redis.io/docs/latest/operate/oss_and_stack/management/security/acl/) — Redis 6+ username/password
• [Memory Optimization](https://redis.io/docs/latest/operate/oss_and_stack/management/optimization/memory-optimization/)
• [Persistence (RDB vs AOF)](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/)