# pardnchiu/go-redis-fallback

> pardnchiu/go-redis-fallback is a Go Redis fallback library by Pardn Chiu (邱敬幃): memory, Redis, and local JSON read tiers with auto recovery.

Maintained by 邱敬幃 Pardn Chiu (pardnchiu), Pardn Co., Ltd. Source: https://github.com/pardnchiu/go-redis-fallback

Full text in one file: [English](https://go-redis-fallback.pardn.io/llms-full.txt) · [中文](https://go-redis-fallback.pardn.io/zh/llms-full.txt)

## Overview

- [Home](https://go-redis-fallback.pardn.io/index.md): pardnchiu/go-redis-fallback is a Go Redis fallback library by Pardn Chiu (邱敬幃): memory, Redis, and local JSON read tiers with auto recovery.
- [Getting Started](https://go-redis-fallback.pardn.io/getting-started.md): Install go-redis-fallback with go get, create the DBPath directory, start an instance, and confirm the current mode from its logs.

## Concepts

- [Core Concepts](https://go-redis-fallback.pardn.io/core-concepts.md): The three storage tiers and three operating modes of go-redis-fallback, and which tier Get, Set, and Del use in each mode.
- [Architecture](https://go-redis-fallback.pardn.io/architecture.md): One overview diagram of go-redis-fallback: read path, batch file writer, health-check ticker, recovery flow, and expiry sweep.

## Read Fallback

- [Normal-Mode Read](https://go-redis-fallback.pardn.io/read-fallback.md): How Get reads memory first, retries Redis MaxRetry times, and switches to fallback mode within the same call when Redis fails.
- [Fallback-Mode Read](https://go-redis-fallback.pardn.io/read-fallback-local.md): How Get restores values from MD5-sharded local JSON files in fallback mode, and why restored numbers come back as float64.
- [Read-Repair](https://go-redis-fallback.pardn.io/read-repair.md): Why a normal-mode memory hit writes the value back to Redis in the background, and how it restores keys stored without a TTL.
- [Expiry on Read](https://go-redis-fallback.pardn.io/read-expiry.md): How go-redis-fallback stores TTL in whole seconds, checks expiry on every read tier, and sweeps expired entries every 30 seconds.

## Recovery

- [Health Check and Mode Switch](https://go-redis-fallback.pardn.io/recovery.md): What switches go-redis-fallback into fallback mode, how the TimeToCheck ping detects a recovered Redis, and startup recovery.
- [Recovery Resync](https://go-redis-fallback.pardn.io/recovery-resync.md): How recovery loads local files, pipelines entries back to Redis with their remaining TTL in batches of 100, and deletes the files.

## Storage

- [Write Path](https://go-redis-fallback.pardn.io/write-path.md): How Set and Del behave in normal and fallback modes, and how fallback writes merge by key in a queue and flush to disk in batches.
- [Local File Format](https://go-redis-fallback.pardn.io/file-storage.md): Path rule and JSON format of go-redis-fallback local files: three-level MD5 sharding, Cache fields, and when files are deleted.

## Reference

- [Configuration](https://go-redis-fallback.pardn.io/configuration.md): go-redis-fallback Config fields and defaults for Redis, Options, and Log, how invalid values are corrected, and tuning tips.
- [API Reference](https://go-redis-fallback.pardn.io/api-reference.md): Signatures, return values, errors, and panics of New, Get, Set, Del, and Close in go-redis-fallback.
- [Type Reference](https://go-redis-fallback.pardn.io/api-reference-types.md): Every exported type in go-redis-fallback: Config, Redis, Options, Log, Cache, RedisFallback, and the internal Writer types.
- [Known Limitations](https://go-redis-fallback.pardn.io/known-limitations.md): Reproduced go-redis-fallback v1.0.0 behaviors that affect read fallback and recovery, each with a workaround.

## Symbols

Exported symbol -> page that documents it.

- `Cache` (.): [API Reference](https://go-redis-fallback.pardn.io/api-reference.md), [Expiry on Read](https://go-redis-fallback.pardn.io/read-expiry.md)
- `Config` (.): [Configuration](https://go-redis-fallback.pardn.io/configuration.md)
- `EmailConfig` (.): [Configuration](https://go-redis-fallback.pardn.io/configuration.md)
- `Log` (.): [Configuration](https://go-redis-fallback.pardn.io/configuration.md), [Getting Started](https://go-redis-fallback.pardn.io/getting-started.md)
- `Logger` (.): [Type Reference](https://go-redis-fallback.pardn.io/api-reference-types.md)
- `New` (.): [Configuration](https://go-redis-fallback.pardn.io/configuration.md), [Expiry on Read](https://go-redis-fallback.pardn.io/read-expiry.md)
- `Options` (.): [API Reference](https://go-redis-fallback.pardn.io/api-reference.md), [Getting Started](https://go-redis-fallback.pardn.io/getting-started.md)
- `Path` (.): [Configuration](https://go-redis-fallback.pardn.io/configuration.md), [Getting Started](https://go-redis-fallback.pardn.io/getting-started.md)
- `Redis` (.): [Configuration](https://go-redis-fallback.pardn.io/configuration.md), [Health Check and Mode Switch](https://go-redis-fallback.pardn.io/recovery.md)
- `RedisFallback` (.): [API Reference](https://go-redis-fallback.pardn.io/api-reference.md)
- `Writer` (.): [Type Reference](https://go-redis-fallback.pardn.io/api-reference-types.md)
- `WriteRequest` (.): [Type Reference](https://go-redis-fallback.pardn.io/api-reference-types.md), [Write Path](https://go-redis-fallback.pardn.io/write-path.md)

## 中文文件

- [首頁](https://go-redis-fallback.pardn.io/zh/index.md): pardnchiu/go-redis-fallback：邱敬幃開發的 Go Redis 降級函式庫，記憶體、Redis、本地 JSON 三層讀取並自動恢復。
- [快速開始](https://go-redis-fallback.pardn.io/zh/getting-started.md): 以 go get 安裝 go-redis-fallback、預先建立 DBPath 目錄、建立實例並從日誌確認目前運作模式。
- [核心概念](https://go-redis-fallback.pardn.io/zh/core-concepts.md): go-redis-fallback 的三層儲存與三種運作模式，以及 Get、Set、Del 在各模式下使用哪一層。
- [架構](https://go-redis-fallback.pardn.io/zh/architecture.md): go-redis-fallback 架構概覽：讀取路徑、批次寫檔、健康檢查 Ticker、恢復流程與過期掃除的關係。
- [正常模式讀取](https://go-redis-fallback.pardn.io/zh/read-fallback.md): 正常模式下 Get 如何先查記憶體、重試 Redis，並在失敗時於同一次呼叫內切入 fallback 模式。
- [Fallback 模式讀取](https://go-redis-fallback.pardn.io/zh/read-fallback-local.md): Fallback 模式下 Get 如何從 MD5 分片的本地 JSON 檔還原資料，以及還原後的型別變化。
- [讀取修補](https://go-redis-fallback.pardn.io/zh/read-repair.md): 正常模式記憶體命中時為何在背景寫回 Redis，以及它如何補回未設 TTL 的鍵。
- [讀取時過期](https://go-redis-fallback.pardn.io/zh/read-expiry.md): go-redis-fallback 如何以整數秒儲存 TTL、在每一層讀取時判斷過期，以及每 30 秒的過期掃除。
- [健康檢查與模式切換](https://go-redis-fallback.pardn.io/zh/recovery.md): 什麼情況會切入 fallback、健康檢查如何以 TimeToCheck 間隔偵測 Redis 恢復，以及啟動時的恢復。
- [恢復回灌](https://go-redis-fallback.pardn.io/zh/recovery-resync.md): 恢復時如何載入本地檔、以剩餘 TTL 每 100 筆 Pipeline 寫回 Redis 並刪除檔案，以及哪些資料不會寫回。
- [寫入路徑](https://go-redis-fallback.pardn.io/zh/write-path.md): Set 與 Del 在正常與 fallback 模式下的行為，以及 fallback 寫入如何經佇列合併後批次落檔。
- [本地檔案格式](https://go-redis-fallback.pardn.io/zh/file-storage.md): go-redis-fallback 本地檔案的路徑規則與 JSON 格式：MD5 三層分片、Cache 欄位與檔案刪除時機。
- [設定](https://go-redis-fallback.pardn.io/zh/configuration.md): go-redis-fallback 的 Config 欄位與預設值：Redis、Options、Log，無效值修正方式與調整建議。
- [API 參考](https://go-redis-fallback.pardn.io/zh/api-reference.md): go-redis-fallback 的 New、Get、Set、Del、Close 簽章、回傳值、錯誤與 panic 條件。
- [型別參考](https://go-redis-fallback.pardn.io/zh/api-reference-types.md): go-redis-fallback 所有匯出型別：Config、Redis、Options、Log、Cache、RedisFallback 與內部型別。
- [已知限制](https://go-redis-fallback.pardn.io/zh/known-limitations.md): go-redis-fallback v1.0.0 中影響讀取降級與恢復的已實測行為，每項附避開方式。

## Optional

- [Release Notes](https://go-redis-fallback.pardn.io/released/index.md): pardnchiu/go-redis-fallback changelog by version