@abtnode/db-cache 1.16.45-beta-20250609-025419-7fd1f86c

package/LICENSE

@@ -0,0 +1,13 @@
+Copyright 2018-2025 ArcBlock
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,170 @@
+# DB Cache
+
+Use Redis or Sqlite3 LRC cache, multithread safe
+
+约定: DB Cache 不能作为数据的单一来源, 我们要假定 Cache 的数据随时可能被释放来进行业务开发.
+不限制 cache 个数: Redis 我们约定直接在 redis 配置好最大内存和达到内存上限时自动移除旧的; Sqlite 由于使用的是硬盘, 也没有必要限制上限.
+
+约定 Redis 启动配置:
+
+- 确保 redis 仅在内网
+- 不做持久化
+- 最大只用 512MB 内存
+- 内存满时对所有键做 LRU (最近最久未使用) 淘汰
+
+```
+docker run -d \
+  --name db-cache-redis \
+  -p 127.0.0.1:40409:6379 \
+  redis:8.0.2 \
+  redis-server \
+    --save "" \
+    --appendonly no \
+    --maxmemory 512mb \
+    --maxmemory-policy allkeys-lru
+```
+
+## Usage
+
+```shell
+yarn add @abtnode/db-cache
+```
+
+Then:
+
+```javascript
+const { DBCache } = require('@abtnode/db-cache');
+
+// 当第一次使用时, 才会去读取配置
+const dbCache = new DBCache(() => ({
+  prefix: 'the prefix key',
+  ttl: 60 * 1000,
+  sqlitePath: 'test.db',
+  redisURL: process.env.REDIS_URL,
+}));
+
+await dbCache.set('key', { foo: 'bar' });
+await dbCache.set('key', { foo: 'bar' }, { ttl: 1000 * 60 * 10 });
+await dbCache.get('key');
+await dbCache.delete('key');
+await dbCache.has('key');
+```
+
+## hash set/get 的使用
+
+```javascript
+const cache = new DBCache(() => ({
+  prefix: 'the prefix key',
+  ttl: 5 * 1000,
+  sqlitePath: 'test.db',
+  redisURL: process.env.REDIS_URL,
+}));
+
+await cache.groupSet('group-key', 'sub-key', { a: 'b' });
+const data = await cache.groupGet('group-key', 'sub-key');
+await cache.groupDel('group-key', 'sub-key');
+await cache.del('group-key'); // delete group all key
+```
+
+## 锁的使用
+
+```javascript
+const lock = new DBCache(() => ({
+  prefix: 'the prefix key',
+  ttl: 5 * 1000,
+  sqlitePath: 'test.db',
+  redisURL: process.env.REDIS_URL,
+}));
+await lock.acquire('key name');
+// do something
+await lock.releaseLock('key name');
+
+// or wait ttl, auto release lock
+```
+
+## SQLite 性能
+
+默认设置压测性能很低,
+
+多线程测试安全, 但是并发非常慢, 放弃所有安全性 (不适合)
+
+使用 WAL (最后使用的方案)
+
+```
+PRAGMA journal_mode = WAL;          -- 写前日志并行读写
+PRAGMA synchronous = OFF;           -- 放弃每次 fsync，追求速度
+PRAGMA busy_timeout = 10000;       -- 锁冲突时最多等 10 秒
+PRAGMA wal_autocheckpoint = 2000;   -- 每 2000 次写后自动做一次 checkpoint
+```
+
+压测结果:
+
+```
+=== SQLite Backend Benchmark ===
+SET  50000 ops in 5.36s -> 9325 ops/sec
+GET  50000 ops in 5.83s -> 8582 ops/sec
+
+=== Redis Backend Benchmark ===
+SET  50000 ops in 0.14s -> 370370 ops/sec
+GET  50000 ops in 0.14s -> 349650 ops/sec
+```
+
+磁盘或硬盘开销:
+
+```
+
+10w 条数据, 数据样本:
+{
+    idx: i,
+    v: `value-${i}`,
+    other: `other-${i}`,
+    other2: `other2-${i}`,
+    other3: `other3-${i}`,
+    other4: `other4-${i}`,
+    other5: `other5-${i}`,
+    other6: `other6-${i}`,
+    other7: `other7-${i}`,
+    other8: `other8-${i}`,
+    other9: `other9-${i}`,
+    other10: `other10-${i}`,
+  }
+
+
+=== Redis Memory Info ===
+# Memory
+used_memory_rss_human:57.41M
+
+SQLite file size: 31.63 MB
+```
+
+并发测试是安全的, 取决于 busy_timeout 的时长和并发数
+
+结论, Redis 大概会是 SQLite 的 20-40 倍性能, 但是 SQLite 不会成为业务的 QPS 瓶颈. SQLite 可以在 RPS 要求不是这么高的情况下, 用硬盘换内存, 还是挺划算的.
+
+#### group 实现差异
+
+group 在 redis 使用 hash set 数据结构, 性能差异较小
+
+sqlite group 相当于使用两个 key 进行查询, 性能也很不错
+
+下面是 group set/get 的性能:
+
+```
+=== SQLite Backend Benchmark ===
+SET  50000 ops in 5.75s -> 8703 ops/sec
+GET  50000 ops in 3.11s -> 16077 ops/sec
+
+=== Redis Backend Benchmark ===
+SET  50000 ops in 0.22s -> 230415 ops/sec
+GET  50000 ops in 0.08s -> 649351 ops/sec
+```
+
+#### CI 测试 redis
+
+有 TEST_REDIS_URL 环境变量就测试 Redis 模式, 没有就测试 SQLite 模式
+
+例子:
+
+```
+TEST_REDIS_URL="redis://:the_password@127.0.0.1:6379"
+```