Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Redis

View as Markdownllms.txt

Redis is a very fast in-memory data store: it keeps small pieces of data in RAM and answers in well under a millisecond. Valkey is its open-source twin (a community fork of Redis that speaks the same protocol), so everything on this page works with either. Apps use Redis for the things that must be fast and shared between servers: the cache, queues, locks, sessions and rate limits.

You don’t need Redis to start. A new Strutvane app keeps all of those in its database (installer question 18, “Cache, queue and sessions”: database, the default). Add Redis when you outgrow that: many servers, lots of queued jobs, or a cache that’s hit thousands of times a second.

Add Redis to an existing app:

Terminal window
node strut install:redis

What you’ll see (something like this):

✔ Installed @strutvane/redis
✔ Wrote config/redis.ts
✔ Docker: added a valkey service to docker/compose.yaml (port 6379)
✔ .env: CACHE_STORE=redis, QUEUE_CONNECTION=redis, REDIS_URL=redis://127.0.0.1:6379
✔ .env.example: CACHE_STORE, QUEUE_CONNECTION, REDIS_URL (no values)
→ Start it: node strut services:up

Start the services and check:

Terminal window
node strut services:up
node strut about

What you’ll see in about, among the other lines:

Cache ............................................ redis
Queue ............................................ redis
Redis ............................. redis://127.0.0.1:6379 (connected)

Your code doesn’t change: Cache.remember() and Queue.push() now talk to Redis.

You can also pick Redis when you create the app, by answering Redis to question 18; the installer then does all of this for you.

Situation Database (default) Redis
One server, modest traffic ✔ simplest, no extra service not needed
Several app servers works (the database is shared) ✔ faster, takes load off the database
Thousands of cache reads a second the database becomes busy ✔
Many queued jobs, many workers works, but polling adds database load ✔ BullMQ, pushes jobs to workers
Locks under heavy contention works ✔
You can’t run another service ✔ —

Rate limits and lockouts already work across servers with the database store (they use the shared cache store, never memory). Redis makes them cheaper, not more correct.

@strutvane/redis registers one driver for each of these. You choose which ones use Redis:

Feature .env key Values
Cache (and rate limits, lockouts, cache locks) CACHE_STORE database, redis
Queues QUEUE_CONNECTION database, redis
Sessions (in config/cache.ts, sessions) database, redis
Broadcasting (coming after 1.0) with @strutvane/realtime redis to share messages between WebSocket servers

A typical split: cache and queues on Redis, sessions in the database (so a Redis restart never signs anyone out).

config/cache.ts
// Cache, queue and sessions. "database" needs no extra service; "redis" needs REDIS_URL in .env.
export default {
store: 'redis',
queue: 'redis',
sessions: 'database',
}

One URL holds everything:

.env
REDIS_URL=redis://127.0.0.1:6379
URL Meaning
redis://127.0.0.1:6379 local, no password
redis://:s3cret@redis.internal:6379 with a password (no user name)
redis://app:s3cret@redis.internal:6379/2 user app, database number 2
rediss://app:s3cret@redis.example.com:6380 TLS (note the double s), for any Redis reached over a network you don’t control

Passwords go only in .env or your host’s secret settings, never in config/redis.ts and never in .env.example. Logs redact the password inside REDIS_URL.

config/redis.ts names connections, like Laravel’s default and cache connections. Use separate ones when you want queues and cache in different Redis databases or servers, so flushing the cache can never delete queued jobs:

config/redis.ts
import { defineConfig, env } from '@strutvane/framework'
export default defineConfig({
default: { url: env.string('REDIS_URL') },
cache: { url: env.string('REDIS_CACHE_URL', env.string('REDIS_URL')) },
prefix: env.string('REDIS_PREFIX', 'my_app:'),
})

Why a prefix: several apps (or your staging and production) may share one Redis. The prefix keeps their keys apart. On top of it, cache keys always get the current team’s prefix (tenant-prefixed cache), which you can’t turn off.

Most apps never talk to Redis directly: the cache, queue and session drivers do. When you need a Redis feature they don’t cover (a sorted set for a leaderboard, a counter, a stream), ask the container for a connection:

app/http/controllers/leaderboard.controller.ts
import type { HttpContext } from '@strutvane/framework'
import { RedisToken, type RedisConnection } from '@strutvane/redis'
export class LeaderboardController {
static readonly inject = [RedisToken] as const
constructor(private readonly redis: RedisConnection) {}
async show(ctx: HttpContext): Promise<Response> {
const top = await this.redis.zrevrange(`leaderboard:${ctx.tenant.id}`, 0, 9, 'WITHSCORES')
return ctx.json({ data: top })
}
}

The connection is the underlying client’s (the catalogue names iovalkey or ioredis), with your prefix applied.

install:redis adds a Valkey service to your local, git-ignored docker/compose.yaml. It starts and stops with the rest:

Terminal window
node strut services:up # app, database, mailpit and valkey
node strut services:logs # includes valkey's log

Like the other services, its port is bound to 127.0.0.1 only, so nothing outside your computer can reach it. If port 6379 is taken, change the forwarded port in .env and run services:up again.

Run Redis or Valkey yourself and point REDIS_URL at it:

macOS:

Terminal window
brew install valkey
brew services start valkey

Linux (Debian, Ubuntu):

Terminal window
sudo apt install redis-server
sudo systemctl enable --now redis-server

Windows: Redis and Valkey don’t ship native Windows builds. Use Docker mode, or install it inside WSL2 with the Linux commands above; redis://127.0.0.1:6379 then works from Windows too.

Use a managed Redis or Valkey from your cloud (or run your own), and:

  1. Turn on TLS and a password, and use rediss:// in REDIS_URL.
  2. Keep it on a private network; never expose 6379 to the internet.
  3. For queues, configure Redis to keep data on disk (AOF persistence) and to not evict keys (maxmemory-policy noeviction). A Redis that evicts keys under memory pressure can silently drop queued jobs.
  4. For a pure cache instance, eviction (allkeys-lru) is fine: losing a cached value only costs a recomputation.

That’s why separate instances for cache and queues are a good idea at scale.

@strutvane/redis registers a ping check with the health-check registry, so the planned /ready route (0.3) fails when Redis is down, and your load balancer stops sending traffic.

What users and you see when Redis is unreachable:

Feature on Redis What happens
Cache requests that need a cached value fail with an error (something like CacheStoreError: The "redis" cache store is unreachable (REDIS_URL).); they don’t silently skip the cache
Rate limits, lockouts fail closed: sign-in and other limited routes are refused rather than left unlimited
Queues dispatching a job fails (the request gets an error); workers pause and reconnect, and no job is lost while Redis keeps its data
Sessions users can’t be recognised, so they’re treated as signed out until Redis is back

The client reconnects by itself when Redis returns. Errors are logged with the connection name, never the password.

Tests don’t need Redis: the testing kit uses in-memory fakes (Cache swapped, Queue.fake()). When you want to test against a real Redis (for example your own sorted-set code), point REDIS_URL at a separate database number for tests (redis://127.0.0.1:6379/15) and flush it before each test.

Error: connect ECONNREFUSED 127.0.0.1:6379

Why: Redis isn’t running, or it runs in Docker and the services are stopped. Fix:

Terminal window
node strut services:up

Without Docker, start your local Redis or Valkey (see above).

ReplyError: NOAUTH Authentication required.

Why: the server has a password and REDIS_URL doesn’t. Fix: REDIS_URL=redis://:your-password@host:6379 (or rediss:// with TLS).

Why: cache and queues share one Redis database, and the flush cleared everything. Fix: give the cache its own connection (REDIS_CACHE_URL, another database number or instance). node strut cache:clear only clears cache keys, but a manual FLUSHDB doesn’t know the difference.

Why: Redis ran out of memory and evicted keys, jobs included. Fix: maxmemory-policy noeviction and more memory for the queue instance, and keep the cache elsewhere.

Everyone was signed out after Redis restarted

Section titled “Everyone was signed out after Redis restarted”

Why: sessions were on a Redis without persistence. Fix: keep sessions in the database (sessions: 'database'), or turn on Redis persistence.