v1.0.0

Core Concepts

Last updated


This page explains the operating modes of go-redis-fallback and which storage tier Get / Set / Del use in each mode.

Three Storage Tiers


TierImplementationLifetime
Memory cachesync.Map holding Cache valuesSame as the instance; entries are removed only on expiry or Del
Redisgithub.com/redis/go-redis/v9 clientPrimary store in normal mode
Local JSON filesFiles under {DBPath}/{DB}/, sharded by the key's MD5Written only during fallback; deleted after recovery

Other Go cache libraries also pair an in-process cache with Redis: eko/gocache chains stores such as memory, Redis, and Memcache; go-redis/cache stores MessagePack values in Redis with an optional local in-process cache; mgtv-tech/jetcache-go and cshum/hybridcache build multi-level caches, and cshum/hybridcache adds cache stampede prevention. The third tier here serves a different purpose: local JSON files hold the data written while Redis is unreachable, and the recovery flow pipelines it back to Redis. ledisdb/redis-failover works on the server side, monitoring Redis and performing failover; go-redis-fallback runs inside the application and does not change the Redis deployment.

Operating Modes


The internal flag isHealth (type.go:57) selects the mode; each Get / Set / Del reads it once at the start.
ModeEntered whenHealth check
NormalThe recovery flow completes (sync.go:89)Not running
FallbackThe startup ping fails, or Redis reads/writes fail MaxRetry timesPings every TimeToCheck
Local-only (no health check)The startup ping succeeds but recovery aborts because {DBPath}/{DB} is missingNot running; the instance stays here

The third mode is not a designed state; it results from the recovery flow returning early.

Operations per Mode


OperationNormal modeFallback / local-only mode
GetMemory → Redis (with retries) → on failure, switch and continue on the local pathMemory → local JSON file
SetWrite Redis (with retries), then memory; on failure, switch and continue on the local pathWrite memory and enqueue a batch file write
DelDelete from memory, file, and RedisDelete from memory and file

Reading Guide


To learnPage
How Get picks a tier in normal mode and when it degradesNormal-Mode Read
How Get restores from files in fallback modeFallback-Mode Read
Why memory hits are written back to RedisRead-Repair
When expired data is removedExpiry on Read
When the instance returns to normal modeHealth Check and Mode Switch
Which data is written back to Redis on recoveryRecovery Resync
中文