resplite 1.4.2 → 1.4.6

package/README.md

@@ -517,16 +517,27 @@ redis-cli -p 6380 PING
 | `RESPLITE_DB` | `./data.db` | SQLite database file |
 | `RESPLITE_PRAGMA_TEMPLATE` | `default` | SQLite PRAGMA preset (see below) |
 
-### PRAGMA templates
+### PRAGMA (convention over configuration)
+
+A **template** is applied by default (`default`); you usually don't pass anything. Only pass **overrides** when you need to change specific pragmas.
 
 | Template | Description | Key settings |
-|---|---|---|
+|----------|-------------|--------------|
 | `default` | Balanced durability and speed (recommended) | WAL, synchronous=NORMAL, 20 MB cache |
 | `performance` | Maximum throughput, reduced crash safety | WAL, synchronous=OFF, 64 MB cache, 512 MB mmap, exclusive locking |
 | `safety` | Crash-safe writes at the cost of speed | WAL, synchronous=FULL, 20 MB cache |
 | `minimal` | Only WAL + foreign keys | WAL, foreign_keys=ON |
 | `none` | No pragmas applied, pure SQLite defaults | - |
 
+Override specific pragmas only when needed. Overrides are applied after the template. Example — 1 GB cache:
+
+```javascript
+const srv = await createRESPlite({
+  db: './data.db',
+  pragma: { cache_size: -1024 * 1024 },  // negative = KiB, so 1 GiB
+});
+```
+
 ## Benchmark (Redis vs RESPLite)
 
 A typical comparison is **Redis (for example, in Docker)** on one side and **RESPLite locally** on the other. In that setup, RESPLite often shows **better latency** because it avoids Docker networking and runs in the same process or host. The benchmark below uses RESPLite with the **default** PRAGMA template only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "resplite",
-  "version": "1.4.2",
+  "version": "1.4.6",
   "description": "A RESP2 server with practical Redis compatibility, backed by SQLite",
   "type": "module",
   "main": "src/index.js",

package/scripts/benchmark-redis-vs-resplite.js

@@ -346,6 +346,13 @@ async function benchZcount(client, n) {
   for (let i = 0; i < n; i++) await client.sendCommand(['ZCOUNT', key, '0', '99']);
 }
 
+async function benchZcard(client, n) {
+  const key = 'bm:zset:card';
+  await client.del(key);
+  await client.zAdd(key, Array.from({ length: 100 }, (_, i) => ({ score: i, value: `m${i}` })));
+  for (let i = 0; i < n; i++) await client.sendCommand(['ZCARD', key]);
+}
+
 async function benchZincrby(client, n) {
   const key = 'bm:zset:incr';
   await client.del(key);
@@ -353,7 +360,31 @@ async function benchZincrby(client, n) {
   for (let i = 0; i < n; i++) await client.sendCommand(['ZINCRBY', key, '1', 'member']);
 }
 
-async function benchZremrangebyrank(client, n) {
+async function benchZremrangebyrankPure(client, n) {
+  const key = 'bm:zset:remrank:pure';
+  const seed = Array.from({ length: 100 }, (_, j) => ({ score: j, value: `m${j}` }));
+  const refill = Array.from({ length: 10 }, (_, j) => ({ score: j, value: `m${j}` }));
+  await client.del(key);
+  await client.zAdd(key, seed);
+  for (let i = 0; i < n; i++) {
+    await client.sendCommand(['ZREMRANGEBYRANK', key, '0', '9']);
+    await client.zAdd(key, refill);
+  }
+}
+
+async function benchZremrangebyscorePure(client, n) {
+  const key = 'bm:zset:remscore:pure';
+  const seed = Array.from({ length: 100 }, (_, j) => ({ score: j, value: `m${j}` }));
+  const refill = Array.from({ length: 10 }, (_, j) => ({ score: j, value: `m${j}` }));
+  await client.del(key);
+  await client.zAdd(key, seed);
+  for (let i = 0; i < n; i++) {
+    await client.sendCommand(['ZREMRANGEBYSCORE', key, '0', '9']);
+    await client.zAdd(key, refill);
+  }
+}
+
+async function benchZremrangebyrankChurn(client, n) {
   const key = 'bm:zset:remrank';
   for (let i = 0; i < n; i++) {
     await client.del(key);
@@ -362,7 +393,7 @@ async function benchZremrangebyrank(client, n) {
   }
 }
 
-async function benchZremrangebyscore(client, n) {
+async function benchZremrangebyscoreChurn(client, n) {
   const key = 'bm:zset:remscore';
   for (let i = 0; i < n; i++) {
     await client.del(key);
@@ -390,6 +421,14 @@ async function benchSrandmember(client, n) {
   for (let i = 0; i < n; i++) await client.sendCommand(['SRANDMEMBER', key]);
 }
 
+async function benchHincrby(client, n) {
+  const key = 'bm:hash:incr';
+  const field = 'counter';
+  await client.del(key);
+  await client.hSet(key, field, '0');
+  for (let i = 0; i < n; i++) await client.sendCommand(['HINCRBY', key, field, '1']);
+}
+
 const FT_INDEX = 'bm_ft_idx';
 const FT_DOCS = 50;
 
@@ -447,11 +486,15 @@ const SUITES = [
   { name: 'LTRIM', fn: benchLtrim, iterScale: 1 },
   { name: 'RENAME', fn: benchRename, iterScale: 1 },
   { name: 'ZCOUNT', fn: benchZcount, iterScale: 1 },
+  { name: 'ZCARD(100)', fn: benchZcard, iterScale: 1 },
   { name: 'ZINCRBY', fn: benchZincrby, iterScale: 1 },
-  { name: 'ZREMRANGEBYRANK', fn: benchZremrangebyrank, iterScale: 1 },
-  { name: 'ZREMRANGEBYSCORE', fn: benchZremrangebyscore, iterScale: 1 },
+  { name: 'ZREMRANGEBYRANK (pure)', fn: benchZremrangebyrankPure, iterScale: 1 },
+  { name: 'ZREMRANGEBYSCORE (pure)', fn: benchZremrangebyscorePure, iterScale: 1 },
+  { name: 'ZREMRANGEBYRANK (churn)', fn: benchZremrangebyrankChurn, iterScale: 1 },
+  { name: 'ZREMRANGEBYSCORE (churn)', fn: benchZremrangebyscoreChurn, iterScale: 1 },
   { name: 'SPOP', fn: benchSpop, iterScale: 1 },
   { name: 'SRANDMEMBER', fn: benchSrandmember, iterScale: 1 },
+  { name: 'HINCRBY', fn: benchHincrby, iterScale: 1 },
   { name: 'FT.SEARCH', fn: benchFtSearch, iterScale: 1 },
 ];
 

package/spec/08-type-sorted-sets.md

@@ -91,8 +91,8 @@ Notes:
 
 * Return cardinality:
 
-  * Prefer `SELECT COUNT(*)` (acceptable).
-  * If performance needs: maintain count in a meta table (not needed initially).
+  * Prefer metadata counter (`redis_keys.zset_count`) for O(1) reads.
+  * Backward compatibility: if counter is missing/null, hydrate once from `SELECT COUNT(*)`.
 
 ### C.5.4 ZSCORE
 

package/src/embed.js

@@ -33,7 +33,8 @@ export { handleConnection, createEngine, openDb };
  * @param {string} [options.db=':memory:']        SQLite file path, or ':memory:' for in-memory.
  * @param {string} [options.host='127.0.0.1']     Host to listen on.
  * @param {number} [options.port=0]               Port to listen on (0 = OS-assigned).
- * @param {string} [options.pragmaTemplate='default'] PRAGMA preset (default|performance|safety|minimal|none).
+ * @param {string} [options.pragmaTemplate='default'] PRAGMA preset (default|performance|safety|minimal|none). Convention: this template is applied by default; no config needed.
+ * @param {Record<string, string|number>} [options.pragma] Override specific pragmas only when needed (e.g. { synchronous: 'FULL' }). Applied after the template.
  * @param {RESPliteHooks} [options.hooks]         Optional event hooks for observability (onUnknownCommand, onCommandError, onSocketError).
  * @param {boolean} [options.gracefulShutdown=true] If true, register SIGTERM/SIGINT to call close(). Set false if you handle shutdown yourself to avoid double handlers.
  * @returns {Promise<{ port: number, host: string, close: () => Promise<void> }>}
@@ -43,10 +44,11 @@ export async function createRESPlite({
   host = '127.0.0.1',
   port = 0,
   pragmaTemplate = 'default',
+  pragma,
   hooks = {},
   gracefulShutdown = true,
 } = {}) {
-  const db = openDb(dbPath, { pragmaTemplate });
+  const db = openDb(dbPath, { pragmaTemplate, pragma });
   const engine = createEngine({ db });
   const connections = new Set();
 

package/src/engine/engine.js

@@ -567,7 +567,11 @@ export function createEngine(opts = {}) {
       if (k.equals(nk)) return;
       runInTransaction(db, () => {
         if (keys.get(nk)) keys.delete(nk);
-        keys.set(nk, meta.type, { expiresAt: meta.expiresAt });
+        keys.set(nk, meta.type, {
+          expiresAt: meta.expiresAt,
+          hashCount: meta.type === KEY_TYPES.HASH ? meta.hashCount : undefined,
+          zsetCount: meta.type === KEY_TYPES.ZSET ? meta.zsetCount : undefined,
+        });
         switch (meta.type) {
           case KEY_TYPES.STRING:
             strings.copyKey(k, nk);

package/src/index.js

@@ -24,6 +24,7 @@ const DEFAULT_PORT = 6379;
  * @param {number} [options.port]
  * @param {string} [options.dbPath]
  * @param {string} [options.pragmaTemplate]
+ * @param {Record<string, string|number>} [options.pragma] Override specific pragmas when needed (e.g. { synchronous: 'FULL' }). Convention: template is applied by default.
  * @param {boolean} [options.gracefulShutdown=true] If true, register SIGTERM/SIGINT to close server and DB. Set false if you handle shutdown yourself.
  */
 export function startServer(options = {}) {
@@ -32,7 +33,7 @@ export function startServer(options = {}) {
   const pragmaTemplate = options.pragmaTemplate ?? process.env.RESPLITE_PRAGMA_TEMPLATE ?? 'default';
   const gracefulShutdown = options.gracefulShutdown !== false;
 
-  const db = openDb(dbPath, { pragmaTemplate });
+  const db = openDb(dbPath, { pragmaTemplate, pragma: options.pragma });
   const cache = createCache({ enabled: true });
   const engine = createEngine({ db, cache });
   const sweeper = createExpirationSweeper({

package/src/storage/sqlite/db.js

@@ -12,7 +12,7 @@ import { applyMigrationSchema } from './migration-schema.js';
 
 /**
  * @param {string} dbPath - Database file path (or ':memory:')
- * @param {object} [options] - Options: pragmaTemplate (default|performance|safety|minimal), plus any better-sqlite3 options
+ * @param {object} [options] - Options: pragmaTemplate (default|performance|safety|minimal), pragma (custom key-value overrides), plus any better-sqlite3 options
  * @returns {import('better-sqlite3').Database}
  */
 export function openDb(dbPath, options = {}) {
@@ -20,9 +20,9 @@ export function openDb(dbPath, options = {}) {
     const dir = path.dirname(dbPath);
     if (dir) fs.mkdirSync(dir, { recursive: true });
   }
-  const { pragmaTemplate = 'default', ...dbOptions } = options;
+  const { pragmaTemplate = 'default', pragma: customPragma, ...dbOptions } = options;
   const db = new Database(dbPath, dbOptions);
-  applyPragmas(db, pragmaTemplate);
+  applyPragmas(db, pragmaTemplate, customPragma);
   applySchema(db);
   applyMigrationSchema(db);
   return db;

package/src/storage/sqlite/hashes.js

@@ -32,15 +32,31 @@ export function createHashesStorage(db, keys) {
       runInTransaction(db, () => {
         const now = options.updatedAt ?? Date.now();
         const meta = keys.get(key);
+        let knownCount = 0;
         if (meta) {
           if (meta.type !== KEY_TYPES.HASH) {
             throw new Error('WRONGTYPE Operation against a key holding the wrong kind of value');
           }
           keys.bumpVersion(key);
+          if (meta.hashCount == null) {
+            const row = countStmt.get(key);
+            knownCount = (row && row.n) || 0;
+            keys.setHashCount(key, knownCount, { touchUpdatedAt: false });
+          } else {
+            knownCount = meta.hashCount;
+          }
         } else {
-          keys.set(key, KEY_TYPES.HASH, { updatedAt: now });
+          keys.set(key, KEY_TYPES.HASH, { updatedAt: now, hashCount: 0 });
         }
+        const existed = getStmt.get(key, field) != null;
         insertStmt.run(key, field, value);
+        if (!existed) {
+          if (meta) keys.incrHashCount(key, 1, { touchUpdatedAt: false });
+          else keys.setHashCount(key, 1, { touchUpdatedAt: false });
+        } else if (meta && meta.hashCount == null) {
+          // Legacy rows may have null counters; persist hydrated value.
+          keys.setHashCount(key, knownCount, { touchUpdatedAt: false });
+        }
       });
     },
 
@@ -48,39 +64,70 @@ export function createHashesStorage(db, keys) {
       runInTransaction(db, () => {
         const now = options.updatedAt ?? Date.now();
         const meta = keys.get(key);
+        let knownCount = 0;
         if (meta) {
           if (meta.type !== KEY_TYPES.HASH) {
             throw new Error('WRONGTYPE Operation against a key holding the wrong kind of value');
           }
           keys.bumpVersion(key);
+          if (meta.hashCount == null) {
+            const row = countStmt.get(key);
+            knownCount = (row && row.n) || 0;
+            keys.setHashCount(key, knownCount, { touchUpdatedAt: false });
+          } else {
+            knownCount = meta.hashCount;
+          }
         } else {
-          keys.set(key, KEY_TYPES.HASH, { updatedAt: now });
+          keys.set(key, KEY_TYPES.HASH, { updatedAt: now, hashCount: 0 });
         }
+        let added = 0;
         for (let i = 0; i < pairs.length; i += 2) {
+          const existed = getStmt.get(key, pairs[i]) != null;
           insertStmt.run(key, pairs[i], pairs[i + 1]);
+          if (!existed) added++;
+        }
+        if (added > 0) {
+          if (meta) keys.incrHashCount(key, added, { touchUpdatedAt: false });
+          else keys.setHashCount(key, added, { touchUpdatedAt: false });
+        } else if (meta && meta.hashCount == null) {
+          // Legacy rows may have null counters; persist hydrated value.
+          keys.setHashCount(key, knownCount, { touchUpdatedAt: false });
         }
       });
     },
 
     delete(key, fields) {
       return runInTransaction(db, () => {
+        const meta = keys.get(key);
+        const before = meta && meta.hashCount != null ? meta.hashCount : null;
         let n = 0;
         for (const field of fields) {
           const r = deleteStmt.run(key, field);
           n += r.changes;
         }
-        const remaining = (countStmt.get(key) || {}).n ?? 0;
+        const remaining = before != null ? Math.max(0, before - n) : ((countStmt.get(key) || {}).n ?? 0);
         if (remaining === 0) {
           deleteAllStmt.run(key);
           keys.delete(key);
+        } else if (n > 0) {
+          keys.setHashCount(key, remaining, { touchUpdatedAt: false });
         }
         return n;
       });
     },
 
     count(key) {
+      const meta = keys.get(key);
+      if (meta && meta.type === KEY_TYPES.HASH && meta.hashCount != null) {
+        return meta.hashCount;
+      }
       const row = countStmt.get(key);
-      return row ? row.n : 0;
+      const n = row ? row.n : 0;
+      if (meta && meta.type === KEY_TYPES.HASH && meta.hashCount == null) {
+        // One-time hydration for databases created before hash_count existed.
+        keys.setHashCount(key, n, { touchUpdatedAt: false });
+      }
+      return n;
     },
 
     incr(key, field, delta, options = {}) {
@@ -91,15 +138,24 @@ export function createHashesStorage(db, keys) {
           throw new Error('WRONGTYPE Operation against a key holding the wrong kind of value');
         }
         if (!meta) {
-          keys.set(key, KEY_TYPES.HASH, { updatedAt: now });
+          keys.set(key, KEY_TYPES.HASH, { updatedAt: now, hashCount: 0 });
         } else {
           keys.bumpVersion(key);
+          if (meta.hashCount == null) {
+            const row = countStmt.get(key);
+            const hydrated = (row && row.n) || 0;
+            keys.setHashCount(key, hydrated, { touchUpdatedAt: false });
+          }
         }
         const cur = getStmt.get(key, field);
         const num = cur == null ? 0 : parseInt(cur.value.toString('utf8'), 10);
         if (Number.isNaN(num)) throw new Error('ERR hash value is not an integer');
         const next = num + delta;
         insertStmt.run(key, field, Buffer.from(String(next), 'utf8'));
+        if (cur == null) {
+          if (meta) keys.incrHashCount(key, 1, { touchUpdatedAt: false });
+          else keys.setHashCount(key, 1, { touchUpdatedAt: false });
+        }
         return next;
       });
     },
@@ -107,9 +163,12 @@ export function createHashesStorage(db, keys) {
     /** Copy all field/value rows from oldKey to newKey. Caller ensures newKey exists in redis_keys. */
     copyKey(oldKey, newKey) {
       const rows = getAllStmt.all(oldKey);
-      for (let i = 0; i < rows.length; i += 2) {
-        insertStmt.run(newKey, rows[i], rows[i + 1]);
+      for (const row of rows) {
+        insertStmt.run(newKey, row[0], row[1]);
       }
+      const sourceMeta = keys.get(oldKey);
+      const nextCount = sourceMeta && sourceMeta.hashCount != null ? sourceMeta.hashCount : rows.length;
+      keys.setHashCount(newKey, nextCount, { touchUpdatedAt: false });
     },
   };
 }

package/src/storage/sqlite/keys.js

@@ -9,16 +9,28 @@ import { KEY_TYPES } from './schema.js';
  */
 export function createKeysStorage(db) {
   const getByKey = db.prepare(
-    'SELECT key, type, expires_at AS expiresAt, version, updated_at AS updatedAt FROM redis_keys WHERE key = ?'
+    'SELECT key, type, expires_at AS expiresAt, hash_count AS hashCount, zset_count AS zsetCount, version, updated_at AS updatedAt FROM redis_keys WHERE key = ?'
   );
   const insert = db.prepare(
-    `INSERT INTO redis_keys (key, type, expires_at, version, updated_at) VALUES (?, ?, ?, 1, ?)`
+    `INSERT INTO redis_keys (key, type, expires_at, hash_count, zset_count, version, updated_at) VALUES (?, ?, ?, ?, ?, 1, ?)`
   );
   const updateMeta = db.prepare(
-    'UPDATE redis_keys SET type = ?, expires_at = ?, version = version + 1, updated_at = ? WHERE key = ?'
+    'UPDATE redis_keys SET type = ?, expires_at = ?, hash_count = ?, zset_count = ?, version = version + 1, updated_at = ? WHERE key = ?'
   );
   const updateExpires = db.prepare('UPDATE redis_keys SET expires_at = ?, updated_at = ? WHERE key = ?');
   const updateVersion = db.prepare('UPDATE redis_keys SET version = version + 1, updated_at = ? WHERE key = ?');
+  const updateHashCount = db.prepare('UPDATE redis_keys SET hash_count = ?, updated_at = ? WHERE key = ?');
+  const updateHashCountOnly = db.prepare('UPDATE redis_keys SET hash_count = ? WHERE key = ?');
+  const incrHashCount = db.prepare(
+    'UPDATE redis_keys SET hash_count = COALESCE(hash_count, 0) + ?, updated_at = ? WHERE key = ?'
+  );
+  const incrHashCountOnly = db.prepare('UPDATE redis_keys SET hash_count = COALESCE(hash_count, 0) + ? WHERE key = ?');
+  const updateZsetCount = db.prepare('UPDATE redis_keys SET zset_count = ?, updated_at = ? WHERE key = ?');
+  const updateZsetCountOnly = db.prepare('UPDATE redis_keys SET zset_count = ? WHERE key = ?');
+  const incrZsetCount = db.prepare(
+    'UPDATE redis_keys SET zset_count = COALESCE(zset_count, 0) + ?, updated_at = ? WHERE key = ?'
+  );
+  const incrZsetCountOnly = db.prepare('UPDATE redis_keys SET zset_count = COALESCE(zset_count, 0) + ? WHERE key = ?');
   const deleteByKey = db.prepare('DELETE FROM redis_keys WHERE key = ?');
   const deleteExpiredStmt = db.prepare('DELETE FROM redis_keys WHERE expires_at IS NOT NULL AND expires_at <= ?');
   const countAll = db.prepare('SELECT COUNT(*) AS n FROM redis_keys').pluck();
@@ -38,10 +50,16 @@ export function createKeysStorage(db) {
       const now = options.updatedAt ?? Date.now();
       const expiresAt = options.expiresAt ?? null;
       const existing = getByKey.get(key);
+      const hashCount = type === KEY_TYPES.HASH
+        ? (options.hashCount ?? existing?.hashCount ?? 0)
+        : null;
+      const zsetCount = type === KEY_TYPES.ZSET
+        ? (options.zsetCount ?? existing?.zsetCount ?? 0)
+        : null;
       if (existing) {
-        updateMeta.run(type, expiresAt, now, key);
+        updateMeta.run(type, expiresAt, hashCount, zsetCount, now, key);
       } else {
-        insert.run(key, type, expiresAt, now);
+        insert.run(key, type, expiresAt, hashCount, zsetCount, now);
       }
     },
 
@@ -53,6 +71,42 @@ export function createKeysStorage(db) {
       updateVersion.run(Date.now(), key);
     },
 
+    setHashCount(key, hashCount, options = {}) {
+      const touchUpdatedAt = options.touchUpdatedAt !== false;
+      if (touchUpdatedAt) {
+        updateHashCount.run(hashCount, options.updatedAt ?? Date.now(), key);
+      } else {
+        updateHashCountOnly.run(hashCount, key);
+      }
+    },
+
+    incrHashCount(key, delta, options = {}) {
+      const touchUpdatedAt = options.touchUpdatedAt !== false;
+      if (touchUpdatedAt) {
+        incrHashCount.run(delta, options.updatedAt ?? Date.now(), key);
+      } else {
+        incrHashCountOnly.run(delta, key);
+      }
+    },
+
+    setZsetCount(key, zsetCount, options = {}) {
+      const touchUpdatedAt = options.touchUpdatedAt !== false;
+      if (touchUpdatedAt) {
+        updateZsetCount.run(zsetCount, options.updatedAt ?? Date.now(), key);
+      } else {
+        updateZsetCountOnly.run(zsetCount, key);
+      }
+    },
+
+    incrZsetCount(key, delta, options = {}) {
+      const touchUpdatedAt = options.touchUpdatedAt !== false;
+      if (touchUpdatedAt) {
+        incrZsetCount.run(delta, options.updatedAt ?? Date.now(), key);
+      } else {
+        incrZsetCountOnly.run(delta, key);
+      }
+    },
+
     delete(key) {
       return deleteByKey.run(key);
     },

package/src/storage/sqlite/pragmas.js

@@ -69,13 +69,29 @@ export function getPragmasForTemplate(name) {
 }
 
 /**
- * Apply pragmas from a named template to an open database.
+ * Apply custom pragma key-value object to an open database.
+ * @param {import('better-sqlite3').Database} db
+ * @param {Record<string, string|number>} obj - e.g. { journal_mode: 'WAL', cache_size: -64000 }
+ */
+function applyPragmaObject(db, obj) {
+  for (const [key, val] of Object.entries(obj)) {
+    if (val === undefined) continue;
+    db.exec(`PRAGMA ${key}=${val};`);
+  }
+}
+
+/**
+ * Apply pragmas from a named template and optional overrides to an open database.
  * @param {import('better-sqlite3').Database} db
  * @param {string} [templateName='default'] - One of: default, performance, safety, minimal, none
+ * @param {Record<string, string|number>} [customPragma] - Optional overrides, e.g. { synchronous: 'FULL', cache_size: -10000 }
  */
-export function applyPragmas(db, templateName = 'default') {
+export function applyPragmas(db, templateName = 'default', customPragma = undefined) {
   const pragmas = getPragmasForTemplate(templateName);
   for (const sql of pragmas) {
     db.exec(sql);
   }
+  if (customPragma && typeof customPragma === 'object' && Object.keys(customPragma).length > 0) {
+    applyPragmaObject(db, customPragma);
+  }
 }

package/src/storage/sqlite/schema.js

@@ -7,6 +7,8 @@ CREATE TABLE IF NOT EXISTS redis_keys (
   key BLOB PRIMARY KEY,
   type INTEGER NOT NULL,
   expires_at INTEGER,
+  hash_count INTEGER,
+  zset_count INTEGER,
   version INTEGER NOT NULL DEFAULT 1,
   updated_at INTEGER NOT NULL
 );
@@ -86,4 +88,14 @@ export const KEY_TYPES = {
  */
 export function applySchema(db) {
   db.exec(SCHEMA);
+  // Backward-compatible migration for databases created before count columns existed.
+  const cols = db.prepare('PRAGMA table_info(redis_keys)').all();
+  const hasHashCount = cols.some((c) => c.name === 'hash_count');
+  const hasZsetCount = cols.some((c) => c.name === 'zset_count');
+  if (!hasHashCount) {
+    db.exec('ALTER TABLE redis_keys ADD COLUMN hash_count INTEGER;');
+  }
+  if (!hasZsetCount) {
+    db.exec('ALTER TABLE redis_keys ADD COLUMN zset_count INTEGER;');
+  }
 }

package/src/storage/sqlite/zsets.js

@@ -26,6 +26,12 @@ export function createZsetsStorage(db, keys) {
     `INSERT INTO redis_zsets (key, member, score) VALUES (?, ?, ?)
      ON CONFLICT(key, member) DO UPDATE SET score = excluded.score`
   );
+  const insertIgnoreStmt = db.prepare(
+    'INSERT OR IGNORE INTO redis_zsets (key, member, score) VALUES (?, ?, ?)'
+  );
+  const updateScoreStmt = db.prepare(
+    'UPDATE redis_zsets SET score = ? WHERE key = ? AND member = ?'
+  );
   const deleteStmt = db.prepare('DELETE FROM redis_zsets WHERE key = ? AND member = ?');
   const deleteAllStmt = db.prepare('DELETE FROM redis_zsets WHERE key = ?');
   const countStmt = db.prepare('SELECT COUNT(*) AS n FROM redis_zsets WHERE key = ?');
@@ -82,19 +88,40 @@ export function createZsetsStorage(db, keys) {
       return runInTransaction(db, () => {
         const now = options.updatedAt ?? Date.now();
         const meta = keys.get(key);
+        let knownCount = 0;
         if (meta) {
           if (meta.type !== KEY_TYPES.ZSET) {
             throw new Error('WRONGTYPE Operation against a key holding the wrong kind of value');
           }
           keys.bumpVersion(key);
+          if (meta.zsetCount == null) {
+            const row = countStmt.get(key);
+            knownCount = (row && row.n) || 0;
+            keys.setZsetCount(key, knownCount, { touchUpdatedAt: false });
+          } else {
+            knownCount = meta.zsetCount;
+          }
         } else {
-          keys.set(key, KEY_TYPES.ZSET, { updatedAt: now });
+          keys.set(key, KEY_TYPES.ZSET, { updatedAt: now, zsetCount: 0 });
         }
         let newCount = 0;
         for (const { score, member } of pairs) {
-          const existed = scoreStmt.get(key, member) != null;
-          upsertStmt.run(key, member, score);
-          if (!existed) newCount++;
+          const inserted = insertIgnoreStmt.run(key, member, score).changes;
+          if (inserted > 0) {
+            newCount++;
+          } else {
+            updateScoreStmt.run(score, key, member);
+          }
+        }
+        if (newCount > 0) {
+          if (meta) {
+            keys.incrZsetCount(key, newCount, { touchUpdatedAt: false });
+          } else {
+            keys.setZsetCount(key, newCount, { touchUpdatedAt: false });
+          }
+        } else if (meta && meta.zsetCount == null) {
+          // Legacy rows may have null counters; persist the hydrated value.
+          keys.setZsetCount(key, knownCount, { touchUpdatedAt: false });
         }
         return newCount;
       });
@@ -108,23 +135,35 @@ export function createZsetsStorage(db, keys) {
      */
     remove(key, members) {
       return runInTransaction(db, () => {
+        const meta = keys.get(key);
+        const before = meta && meta.zsetCount != null ? meta.zsetCount : null;
         let n = 0;
         for (const m of members) {
           n += deleteStmt.run(key, m).changes;
         }
-        const row = countStmt.get(key);
-        const remaining = (row && row.n) || 0;
+        const remaining = before != null ? Math.max(0, before - n) : ((countStmt.get(key) || {}).n || 0);
         if (remaining === 0) {
           deleteAllStmt.run(key);
           keys.delete(key);
+        } else if (n > 0) {
+          keys.setZsetCount(key, remaining, { touchUpdatedAt: false });
         }
         return n;
       });
     },
 
     count(key) {
+      const meta = keys.get(key);
+      if (meta && meta.type === KEY_TYPES.ZSET && meta.zsetCount != null) {
+        return meta.zsetCount;
+      }
       const row = countStmt.get(key);
-      return row ? row.n : 0;
+      const n = row ? row.n : 0;
+      if (meta && meta.type === KEY_TYPES.ZSET && meta.zsetCount == null) {
+        // One-time hydration for databases created before zset_count existed.
+        keys.setZsetCount(key, n, { touchUpdatedAt: false });
+      }
+      return n;
     },
 
     score(key, member) {
@@ -270,6 +309,9 @@ export function createZsetsStorage(db, keys) {
       for (const r of rows) {
         upsertStmt.run(newKey, r.member, r.score);
       }
+      const sourceMeta = keys.get(oldKey);
+      const nextCount = sourceMeta && sourceMeta.zsetCount != null ? sourceMeta.zsetCount : rows.length;
+      keys.setZsetCount(newKey, nextCount, { touchUpdatedAt: false });
     },
 
     countByScore(key, min, max) {
@@ -285,14 +327,23 @@ export function createZsetsStorage(db, keys) {
           throw new Error('WRONGTYPE Operation against a key holding the wrong kind of value');
         }
         if (!meta) {
-          keys.set(key, KEY_TYPES.ZSET, { updatedAt: now });
+          keys.set(key, KEY_TYPES.ZSET, { updatedAt: now, zsetCount: 0 });
         } else {
           keys.bumpVersion(key);
+          if (meta.zsetCount == null) {
+            const row = countStmt.get(key);
+            const hydrated = (row && row.n) || 0;
+            keys.setZsetCount(key, hydrated, { touchUpdatedAt: false });
+          }
         }
         const cur = scoreStmt.get(key, member);
         const prev = cur == null ? 0 : cur.score;
         const next = prev + increment;
         upsertStmt.run(key, member, next);
+        if (cur == null) {
+          if (meta) keys.incrZsetCount(key, 1, { touchUpdatedAt: false });
+          else keys.setZsetCount(key, 1, { touchUpdatedAt: false });
+        }
         return formatScore(next);
       });
     },
@@ -318,6 +369,8 @@ export function createZsetsStorage(db, keys) {
         if (remaining === 0) {
           deleteAllStmt.run(key);
           keys.delete(key);
+        } else if (n > 0) {
+          keys.setZsetCount(key, remaining, { touchUpdatedAt: false });
         }
         return n;
       });
@@ -333,6 +386,7 @@ export function createZsetsStorage(db, keys) {
           keys.delete(key);
         } else if (r.changes > 0) {
           keys.bumpVersion(key);
+          keys.setZsetCount(key, n, { touchUpdatedAt: false });
         }
         return r.changes;
       });

package/test/integration/embed.test.js

@@ -89,6 +89,17 @@ describe('createRESPlite', () => {
     await srv.close();
   });
 
+  it('accepts pragma overrides (convention: template first, overrides only when needed)', async () => {
+    const srv = await createRESPlite({
+      pragma: { synchronous: 'FULL', cache_size: -10_000 },
+    });
+    const client = await redisClient(srv.port);
+    await client.set('k', 'v');
+    assert.equal(await client.get('k'), 'v');
+    await client.quit();
+    await srv.close();
+  });
+
   it('unsupported command still returns ERR command not supported yet to client', async () => {
     const srv = await createRESPlite();
     const client = await redisClient(srv.port);

package/test/integration/hashes.test.js

@@ -1,5 +1,6 @@
 import { describe, it, before, after } from 'node:test';
 import assert from 'node:assert/strict';
+import Database from 'better-sqlite3';
 import { createTestServer } from '../helpers/server.js';
 import { sendCommand, argv } from '../helpers/client.js';
 import { tryParseValue } from '../../src/resp/parser.js';
@@ -56,4 +57,33 @@ describe('Hashes integration', () => {
     const reply = await sendCommand(port, argv('HLEN', 'hlen:str'));
     assert.ok(reply.toString('utf8').includes('WRONGTYPE'));
   });
+
+  it('RENAME keeps hash cardinality metadata', async () => {
+    await sendCommand(port, argv('HSET', 'hrename:src', 'a', '1', 'b', '2', 'c', '3'));
+    await sendCommand(port, argv('RENAME', 'hrename:src', 'hrename:dst'));
+    const reply = await sendCommand(port, argv('HLEN', 'hrename:dst'));
+    assert.equal(tryParseValue(reply, 0).value, 3);
+  });
+
+  it('legacy hash rows with null hash_count hydrate on first HLEN', async () => {
+    const s1 = await createTestServer();
+    await sendCommand(s1.port, argv('HSET', 'legacy:h', 'f1', 'v1', 'f2', 'v2'));
+    const dbPath = s1.dbPath;
+    await s1.closeAsync();
+    s1.db.close();
+
+    const legacyDb = new Database(dbPath);
+    legacyDb.prepare('UPDATE redis_keys SET hash_count = NULL WHERE key = ?').run(Buffer.from('legacy:h', 'utf8'));
+    legacyDb.close();
+
+    const s2 = await createTestServer({ dbPath });
+    const first = await sendCommand(s2.port, argv('HLEN', 'legacy:h'));
+    assert.equal(tryParseValue(first, 0).value, 2);
+    const second = await sendCommand(s2.port, argv('HLEN', 'legacy:h'));
+    assert.equal(tryParseValue(second, 0).value, 2);
+
+    const row = s2.db.prepare('SELECT hash_count AS n FROM redis_keys WHERE key = ?').get(Buffer.from('legacy:h', 'utf8'));
+    assert.equal(row.n, 2);
+    await s2.closeAsync();
+  });
 });

package/test/integration/zsets.test.js

@@ -1,5 +1,6 @@
 import { describe, it, before, after } from 'node:test';
 import assert from 'node:assert/strict';
+import Database from 'better-sqlite3';
 import { createTestServer } from '../helpers/server.js';
 import { sendCommand, argv } from '../helpers/client.js';
 import { tryParseValue } from '../../src/resp/parser.js';
@@ -40,6 +41,15 @@ describe('ZSET integration', () => {
     assert.equal(score.toString('utf8'), '20');
   });
 
+  it('ZADD with duplicate member in same command counts as new once and keeps last score', async () => {
+    const added = await sendCommand(port, argv('ZADD', 'zdup', '1', 'm', '2', 'm'));
+    assert.equal(tryParseValue(added, 0).value, 1);
+
+    const scoreReply = await sendCommand(port, argv('ZSCORE', 'zdup', 'm'));
+    const score = tryParseValue(scoreReply, 0).value;
+    assert.equal(score.toString('utf8'), '2');
+  });
+
   it('ZRANGE WITHSCORES returns member, score, ...', async () => {
     await sendCommand(port, argv('ZADD', 'z3', '1', 'x', '2', 'y'));
     const reply = await sendCommand(port, argv('ZRANGE', 'z3', '0', '-1', 'WITHSCORES'));
@@ -201,6 +211,35 @@ describe('ZSET integration', () => {
     await s2.closeAsync();
   });
 
+  it('RENAME keeps zset cardinality metadata', async () => {
+    await sendCommand(port, argv('ZADD', 'zrename_src', '1', 'a', '2', 'b', '3', 'c'));
+    await sendCommand(port, argv('RENAME', 'zrename_src', 'zrename_dst'));
+    const cardReply = await sendCommand(port, argv('ZCARD', 'zrename_dst'));
+    assert.equal(tryParseValue(cardReply, 0).value, 3);
+  });
+
+  it('legacy zset rows with null zset_count hydrate on first ZCARD', async () => {
+    const s1 = await createTestServer();
+    await sendCommand(s1.port, argv('ZADD', 'legacy_z', '1', 'one', '2', 'two'));
+    const dbPath = s1.dbPath;
+    await s1.closeAsync();
+    s1.db.close();
+
+    const legacyDb = new Database(dbPath);
+    legacyDb.prepare('UPDATE redis_keys SET zset_count = NULL WHERE key = ?').run(Buffer.from('legacy_z', 'utf8'));
+    legacyDb.close();
+
+    const s2 = await createTestServer({ dbPath });
+    const first = await sendCommand(s2.port, argv('ZCARD', 'legacy_z'));
+    assert.equal(tryParseValue(first, 0).value, 2);
+    const second = await sendCommand(s2.port, argv('ZCARD', 'legacy_z'));
+    assert.equal(tryParseValue(second, 0).value, 2);
+
+    const row = s2.db.prepare('SELECT zset_count AS n FROM redis_keys WHERE key = ?').get(Buffer.from('legacy_z', 'utf8'));
+    assert.equal(row.n, 2);
+    await s2.closeAsync();
+  });
+
   it('binary-safe zset members', async () => {
     const bin = Buffer.from([0x00, 0xff]);
     await sendCommand(port, argv('ZADD', 'zbin', '1', 'normal'));

package/test/unit/pragmas.test.js

@@ -72,4 +72,28 @@ describe('Pragma templates', () => {
       db.close();
     }
   });
+
+  it('openDb with pragma overrides applies them after the template', () => {
+    const path = tmpDbPath();
+    const db = openDb(path, { pragmaTemplate: 'default', pragma: { synchronous: 'FULL' } });
+    try {
+      const row = db.prepare('PRAGMA synchronous').get();
+      assert.equal(row.synchronous, 2); // FULL = 2
+    } finally {
+      db.close();
+    }
+  });
+
+  it('openDb with pragma cache_size override (e.g. 1 GiB)', () => {
+    const path = tmpDbPath();
+    const oneGibKib = 1024 * 1024;
+    const db = openDb(path, { pragmaTemplate: 'default', pragma: { cache_size: -oneGibKib } });
+    try {
+      const row = db.prepare('PRAGMA cache_size').get();
+      // SQLite returns cache size in KiB when it was set negative
+      assert.equal(Math.abs(row.cache_size), oneGibKib);
+    } finally {
+      db.close();
+    }
+  });
 });

package/docs/generated/migration-apply-dirty-concurrency-progress.md

@@ -1,7 +0,0 @@
----
-id: 90dhbsvf0f
-type: implementation
-title: Apply dirty migration concurrency and progress
-created: '2026-03-12 14:55:12'
----
-Improved src/migration/apply-dirty.js to support concurrent dirty-key apply via options.concurrency (chunked Promise.all worker model) while preserving max_rps throttling. Added richer onProgress payload fields: dirty_keys_processed, dirty_pending, dirty_keys_per_second, dirty_eta_seconds, and related counters. Exposed new options through createMigration().applyDirty: concurrency and progressIntervalMs. Updated README migration cutover snippet with high-throughput applyDirty example and progress logging. Added unit test test/unit/migration-apply-dirty.test.js validating concurrency and progress payload. Verified with node --test test/unit/migration-apply-dirty.test.js and npm run test:unit (all passing).

package/docs/generated/migration-bulk-concurrency.md

@@ -1,7 +0,0 @@
----
-id: tucj9i5nh5
-type: implementation
-title: Bulk migration concurrency added
-created: '2026-03-11 11:09:20'
----
-Added configurable concurrency to runBulkImport and createMigration.bulk with default 1. Implemented chunked parallel import with shared global max_rps limiter. Added unit tests proving default sequential behavior and concurrent behavior with cap.

package/docs/generated/migration-bulk-eta-onprogress.md

@@ -1,7 +0,0 @@
----
-id: 105jsp012x
-type: implementation
-title: Bulk onProgress ETA support
-created: '2026-03-11 11:10:48'
----
-Added ETA/progress metrics to bulk migration onProgress payload. New optional options: estimated_total_keys in runBulkImport, estimatedTotalKeys in createMigration/bulk(). onProgress payload now includes elapsed_seconds, keys_per_second, estimated_total_keys, remaining_keys_estimate, eta_seconds, progress_pct. README migration example updated to print ETA/rate. Added unit test validating ETA fields and final 100%/eta=0 behavior.