Core Concepts
This page explains the operating modes of go-redis-fallback and which storage tier Get / Set / Del use in each mode.
Three Storage Tiers
| Tier | Implementation | Lifetime |
|---|---|---|
| Memory cache | sync.Map holding Cache values |
Same as the instance; entries are removed only on expiry |
| Redis | github.com/redis/go-redis/v9 client |
Primary store in normal mode |
| Local JSON files | Files under {DBPath}/{DB}/, sharded by the key's MD5 |
Written only during fallback; deleted after recovery |
Operating Modes
The internal flag isHealth (type.go:57) selects the mode; each Get / Set / Del reads it once at the start.
| Mode | Entered when | Health check |
|---|---|---|
| Normal | The recovery flow completes (sync.go:89) |
Not running |
| Fallback | The startup ping fails, or Redis reads/writes fail MaxRetry times |
Pings every TimeToCheck |
| Local-only (no health check) | The startup ping succeeds but recovery aborts because {DBPath}/{DB} is missing |
Not running; the instance stays here |
The third mode is not a designed state; it results from the recovery flow returning early. See Known Limitations.
Operations per Mode
| Operation | Normal mode | Fallback / local-only mode |
|---|---|---|
Get |
Memory → Redis (with retries) → on failure, switch and continue on the local path | Memory → local JSON file |
Set |
Write Redis (with retries), then memory; on failure, switch and continue on the local path | Write memory and enqueue a batch file write |
Del |
Delete from memory, file, and Redis | Delete from memory and file |
Reading Guide
| To learn | Page |
|---|---|
How Get picks a tier in normal mode and when it degrades |
Normal-Mode Read |
How Get restores from files in fallback mode |
Fallback-Mode Read |
| Why memory hits are written back to Redis | Read-Repair |
| When expired data is removed | Expiry on Read |
| When the instance returns to normal mode | Health Check and Mode Switch |
| Which data is written back to Redis on recovery | Recovery Resync |