@zero-server/sdk 0.9.0 → 0.9.2

package/lib/orm/adapters/redis.js

@@ -1,1534 +1,1534 @@
-/**
- * @module orm/adapters/redis
- * @description Redis database adapter for the zero-server ORM.
- *              Uses `ioredis` as the driver. Stores table data as Redis hashes
- *              with sorted-set indexes for ordering and filtering.
- *
- *              Bring-your-own-driver: `npm install ioredis`
- *
- *              Supports full ORM CRUD, key-value operations, pub/sub,
- *              pipelines, TTL, and all DDL/migration methods.
- *
- * @example
- *   // Connect by host/port
- *   const db = Database.connect('redis', { host: '127.0.0.1', port: 6379 });
- *
- *   // Connect by URL with authentication
- *   const db2 = Database.connect('redis', { url: 'redis://user:pass@host:6379/0' });
- *
- *   // Connect with key prefix
- *   const db3 = Database.connect('redis', { url: 'redis://host:6379', prefix: 'myapp:' });
- */
-
-let Redis;
-try { Redis = require('ioredis'); } catch (_) { /* loaded lazily */ }
-
-/**
- * ReDoS-safe SQL LIKE matcher using iterative DP.
- * % = any sequence of chars, _ = any single char. Case-insensitive.
- * @private
- */
-function _likeSafe(str, pattern)
-{
-    const s = str.toLowerCase();
-    const p = pattern.toLowerCase();
-    const sLen = s.length, pLen = p.length;
-    let dp = new Array(pLen + 1).fill(false);
-    dp[0] = true;
-    for (let j = 0; j < pLen; j++) { if (p[j] === '%') dp[j + 1] = dp[j]; }
-    for (let i = 1; i <= sLen; i++)
-    {
-        const next = new Array(pLen + 1).fill(false);
-        for (let j = 1; j <= pLen; j++)
-        {
-            if (p[j - 1] === '%')       next[j] = dp[j] || next[j - 1];
-            else if (p[j - 1] === '_')  next[j] = dp[j - 1];
-            else                        next[j] = dp[j - 1] && s[i - 1] === p[j - 1];
-        }
-        dp = next;
-    }
-    return dp[pLen];
-}
-
-class RedisAdapter
-{
-    /**
-     * @constructor
-     * @param {object} [options] - Configuration options.
-     * @param {string} [options.url]             - Redis connection URL.
-     * @param {string} [options.host='127.0.0.1'] - Redis host.
-     * @param {number} [options.port=6379]       - Redis port.
-     * @param {string} [options.password]        - Redis password.
-     * @param {number} [options.db=0]            - Redis database index.
-     * @param {string} [options.prefix='zh:']    - Key prefix for namespacing.
-     * @param {number} [options.maxRetries=3]    - Max connection retries.
-     * @param {boolean} [options.lazyConnect=false] - If true, defer connection until first operation.
-     * @param {object} [options.tls]             - TLS options for secure connections.
-     * @param {string} [options.keyPrefix]       - Alias for prefix (ioredis compat).
-     * @param {number} [options.connectTimeout=10000] - Connection timeout in ms.
-     */
-    constructor(options = {})
-    {
-        if (!Redis)
-        {
-            throw new Error(
-                'Redis adapter requires the "ioredis" package.\n' +
-                'Install it with: npm install ioredis'
-            );
-        }
-
-        // Validate options at the boundary
-        if (options.host !== undefined && (typeof options.host !== 'string' || !options.host.length))
-            throw new Error('Redis: host must be a non-empty string');
-        if (options.port !== undefined)
-        {
-            const p = Number(options.port);
-            if (!Number.isInteger(p) || p < 1 || p > 65535)
-                throw new Error('Redis: port must be an integer between 1 and 65535');
-        }
-        if (options.db !== undefined)
-        {
-            const d = Number(options.db);
-            if (!Number.isInteger(d) || d < 0 || d > 15)
-                throw new Error('Redis: db must be an integer between 0 and 15');
-        }
-        if (options.password !== undefined && typeof options.password !== 'string')
-            throw new Error('Redis: password must be a string');
-        if (options.url !== undefined && typeof options.url !== 'string')
-            throw new Error('Redis: url must be a string');
-        if (options.prefix !== undefined && typeof options.prefix !== 'string')
-            throw new Error('Redis: prefix must be a string');
-        if (options.connectTimeout !== undefined)
-        {
-            const ct = Number(options.connectTimeout);
-            if (!Number.isFinite(ct) || ct < 0)
-                throw new Error('Redis: connectTimeout must be a non-negative number');
-        }
-
-        this._prefix = options.prefix || options.keyPrefix || 'zh:';
-        this._schemas = new Map();
-        this._indexes = new Map();
-        this._subscribers = new Map();
-
-        // Build ioredis config
-        const config = {};
-        if (options.url)
-        {
-            this._client = new Redis(options.url, {
-                maxRetriesPerRequest: options.maxRetries || 3,
-                lazyConnect: options.lazyConnect || false,
-                connectTimeout: options.connectTimeout || 10000,
-                tls: options.tls,
-                keyPrefix: undefined, // we manage prefix ourselves
-            });
-        }
-        else
-        {
-            config.host = options.host || '127.0.0.1';
-            config.port = options.port || 6379;
-            if (options.password) config.password = options.password;
-            if (options.db !== undefined) config.db = options.db;
-            config.maxRetriesPerRequest = options.maxRetries || 3;
-            config.lazyConnect = options.lazyConnect || false;
-            config.connectTimeout = options.connectTimeout || 10000;
-            if (options.tls) config.tls = options.tls;
-
-            this._client = new Redis(config);
-        }
-
-        // Separate client for pub/sub (subscribers block the connection)
-        this._subClient = null;
-    }
-
-    // -- Key Helpers --------------------------------------
-
-    /** @private Validate a table name or key to prevent internal key collision. */
-    _validateKey(key, label = 'key')
-    {
-        if (typeof key !== 'string' || key.length === 0)
-            throw new Error(`Redis: ${label} must be a non-empty string`);
-        if (/[\x00-\x1f]/.test(key))
-            throw new Error(`Redis: ${label} must not contain control characters`);
-    }
-
-    /** @private Build a prefixed key for a table's metadata. */
-    _key(table, ...parts)
-    {
-        return this._prefix + table + (parts.length ? ':' + parts.join(':') : '');
-    }
-
-    /** @private Key for a table's row hash: zh:users:row:42 */
-    _rowKey(table, id)
-    {
-        return this._key(table, 'row', String(id));
-    }
-
-    /** @private Key for a table's ID index sorted set: zh:users:_ids */
-    _idsKey(table)
-    {
-        return this._key(table, '_ids');
-    }
-
-    /** @private Key for a table's auto-increment counter: zh:users:_seq */
-    _seqKey(table)
-    {
-        return this._key(table, '_seq');
-    }
-
-    /** @private Key for a table's schema definition: zh:users:_schema */
-    _schemaKey(table)
-    {
-        return this._key(table, '_schema');
-    }
-
-    /** @private Serialize a row for storage. */
-    _serialize(row)
-    {
-        return JSON.stringify(row);
-    }
-
-    /** @private Deserialize a stored row. */
-    _deserialize(data)
-    {
-        if (data === null || data === undefined) return null;
-        try { return JSON.parse(data); }
-        catch (_) { return null; }
-    }
-
-    // -- Table Management ---------------------------------
-
-    /**
-     * Create a table (register schema + initialize index).
-     * @param {string} table - Table name.
-     * @param {object} [schema] - Schema definition.
-     */
-    async createTable(table, schema)
-    {
-        this._validateKey(table, 'table name');
-        if (schema)
-        {
-            this._schemas.set(table, schema);
-            await this._client.set(this._schemaKey(table), JSON.stringify(schema));
-        }
-        // Ensure the sequence key exists
-        const exists = await this._client.exists(this._seqKey(table));
-        if (!exists) await this._client.set(this._seqKey(table), '0');
-    }
-
-    /**
-     * Drop a table (delete all keys).
-     * @param {string} table - Table name.
-     */
-    async dropTable(table)
-    {
-        // Get all row IDs
-        const ids = await this._client.zrange(this._idsKey(table), 0, -1);
-        const pipeline = this._client.pipeline();
-
-        for (const id of ids)
-        {
-            pipeline.del(this._rowKey(table, id));
-        }
-        pipeline.del(this._idsKey(table));
-        pipeline.del(this._seqKey(table));
-        pipeline.del(this._schemaKey(table));
-
-        // Delete any field index keys
-        const schema = this._schemas.get(table);
-        if (schema)
-        {
-            for (const col of Object.keys(schema))
-            {
-                pipeline.del(this._key(table, 'idx', col));
-            }
-        }
-
-        await pipeline.exec();
-        this._schemas.delete(table);
-        this._indexes.delete(table);
-    }
-
-    // -- CRUD Operations ----------------------------------
-
-    /**
-     * Insert a row.
-     * @param {string} table - Table name.
-     * @param {object} data - Record data object.
-     * @returns {Promise<object>} Inserted row with ID.
-     */
-    async insert(table, data)
-    {
-        const row = { ...data };
-
-        // Auto-increment if no ID provided
-        if (row.id === undefined || row.id === null)
-        {
-            row.id = await this._client.incr(this._seqKey(table));
-        }
-        else
-        {
-            // Ensure sequence is ahead of manual IDs
-            const current = parseInt(await this._client.get(this._seqKey(table)) || '0', 10);
-            if (typeof row.id === 'number' && row.id >= current)
-            {
-                await this._client.set(this._seqKey(table), String(row.id + 1));
-            }
-        }
-
-        // Serialize dates
-        for (const [k, v] of Object.entries(row))
-        {
-            if (v instanceof Date) row[k] = v.toISOString();
-        }
-
-        // Enforce unique constraints
-        await this._enforceUnique(table, row);
-
-        // Store the row as a JSON string
-        const pipeline = this._client.pipeline();
-        pipeline.set(this._rowKey(table, row.id), this._serialize(row));
-        // Add to sorted set index (score = numeric id for ordering)
-        pipeline.zadd(this._idsKey(table), Number(row.id) || 0, String(row.id));
-
-        await pipeline.exec();
-
-        return row;
-    }
-
-    /**
-     * Insert multiple rows.
-     * @param {string} table - Table name.
-     * @param {object[]} dataArray - Array of record objects.
-     * @returns {Promise<object[]>} Array of inserted rows.
-     */
-    async insertMany(table, dataArray)
-    {
-        const results = [];
-        for (const data of dataArray) results.push(await this.insert(table, data));
-        return results;
-    }
-
-    /**
-     * Update a row by primary key.
-     * @param {string} table - Table name.
-     * @param {string} pk - Primary key column name.
-     * @param {*} pkVal - Primary key value.
-     * @param {object} data - Record data object.
-     */
-    async update(table, pk, pkVal, data)
-    {
-        const key = this._rowKey(table, pkVal);
-        const existing = this._deserialize(await this._client.get(key));
-        if (!existing) return;
-
-        for (const [k, v] of Object.entries(data))
-        {
-            existing[k] = v instanceof Date ? v.toISOString() : v;
-        }
-
-        await this._client.set(key, this._serialize(existing));
-    }
-
-    /**
-     * Update all rows matching conditions.
-     * @param {string} table - Table name.
-     * @param {object} conditions - Filter conditions.
-     * @param {object} data - Record data object.
-     * @returns {Promise<number>} Number of updated rows.
-     */
-    async updateWhere(table, conditions, data)
-    {
-        const rows = await this._getAllRows(table);
-        let count = 0;
-
-        const pipeline = this._client.pipeline();
-        for (const row of rows)
-        {
-            if (this._matchConditions(row, conditions))
-            {
-                for (const [k, v] of Object.entries(data))
-                {
-                    row[k] = v instanceof Date ? v.toISOString() : v;
-                }
-                pipeline.set(this._rowKey(table, row.id), this._serialize(row));
-                count++;
-            }
-        }
-        if (count > 0) await pipeline.exec();
-        return count;
-    }
-
-    /**
-     * Remove a row by primary key.
-     * @param {string} table - Table name.
-     * @param {string} pk - Primary key column name.
-     * @param {*} pkVal - Primary key value.
-     */
-    async remove(table, pk, pkVal)
-    {
-        const pipeline = this._client.pipeline();
-        pipeline.del(this._rowKey(table, pkVal));
-        pipeline.zrem(this._idsKey(table), String(pkVal));
-        await pipeline.exec();
-    }
-
-    /**
-     * Delete all rows matching conditions.
-     * @param {string} table - Table name.
-     * @param {object} conditions - Filter conditions.
-     * @returns {Promise<number>} Number of deleted rows.
-     */
-    async deleteWhere(table, conditions)
-    {
-        const rows = await this._getAllRows(table);
-        let count = 0;
-
-        const pipeline = this._client.pipeline();
-        for (const row of rows)
-        {
-            if (this._matchConditions(row, conditions))
-            {
-                pipeline.del(this._rowKey(table, row.id));
-                pipeline.zrem(this._idsKey(table), String(row.id));
-                count++;
-            }
-        }
-        if (count > 0) await pipeline.exec();
-        return count;
-    }
-
-    // -- Query Execution ----------------------------------
-
-    /**
-     * Execute a query descriptor (from the Query builder).
-     * @param {object} descriptor - Query descriptor object.
-     * @returns {Promise<Array|number>} Matching rows, or count if action is `'count'`.
-     */
-    async execute(descriptor)
-    {
-        const { action, table, fields, where, orderBy, limit, offset, distinct, groupBy, having } = descriptor;
-        let rows = await this._getAllRows(table);
-
-        // Apply WHERE filters
-        if (where && where.length > 0)
-        {
-            rows = rows.filter(row => this._applyWhereChain(row, where));
-        }
-
-        // Count action
-        if (action === 'count') return rows.length;
-
-        // GROUP BY
-        if (groupBy && groupBy.length > 0)
-        {
-            const groups = new Map();
-            for (const row of rows)
-            {
-                const key = groupBy.map(f => row[f]).join('\0');
-                if (!groups.has(key)) groups.set(key, { _key: {}, _rows: [] });
-                const g = groups.get(key);
-                for (const f of groupBy) g._key[f] = row[f];
-                g._rows.push(row);
-            }
-            rows = [];
-            for (const g of groups.values())
-            {
-                const row = { ...g._key };
-                row._groupRows = g._rows;
-                rows.push(row);
-            }
-
-            // HAVING
-            if (having && having.length > 0)
-            {
-                rows = rows.filter(row =>
-                {
-                    for (const h of having)
-                    {
-                        let actual;
-                        if (h.field === 'COUNT(*)' || h.field.startsWith('COUNT'))
-                        {
-                            actual = row._groupRows.length;
-                        }
-                        else
-                        {
-                            actual = row[h.field];
-                        }
-                        if (!this._compareOp(actual, h.op, h.value)) return false;
-                    }
-                    return true;
-                });
-            }
-
-            for (const row of rows) delete row._groupRows;
-        }
-
-        // ORDER BY
-        if (orderBy && orderBy.length > 0)
-        {
-            rows.sort((a, b) =>
-            {
-                for (const { field, dir } of orderBy)
-                {
-                    const av = a[field], bv = b[field];
-                    if (av < bv) return dir === 'ASC' ? -1 : 1;
-                    if (av > bv) return dir === 'ASC' ? 1 : -1;
-                }
-                return 0;
-            });
-        }
-
-        // OFFSET
-        if (offset) rows = rows.slice(offset);
-
-        // LIMIT
-        if (limit) rows = rows.slice(0, limit);
-
-        // SELECT specific fields
-        if (fields && fields.length > 0)
-        {
-            rows = rows.map(row =>
-            {
-                const filtered = {};
-                for (const f of fields) filtered[f] = row[f];
-                return filtered;
-            });
-        }
-
-        // DISTINCT
-        if (distinct)
-        {
-            const seen = new Set();
-            rows = rows.filter(row =>
-            {
-                const key = JSON.stringify(row);
-                if (seen.has(key)) return false;
-                seen.add(key);
-                return true;
-            });
-        }
-
-        return rows;
-    }
-
-    /**
-     * Compute an aggregate value.
-     * @param {object} descriptor - Query descriptor object.
-     * @returns {Promise<number|null>} Computed aggregate value.
-     */
-    async aggregate(descriptor)
-    {
-        const { table, where, aggregateFn, aggregateField } = descriptor;
-        let rows = await this._getAllRows(table);
-        if (where && where.length > 0)
-        {
-            rows = rows.filter(row => this._applyWhereChain(row, where));
-        }
-        const fn = aggregateFn.toLowerCase();
-        if (!rows.length) return (fn === 'count' || fn === 'avg' || fn === 'sum') ? 0 : null;
-        switch (fn)
-        {
-            case 'sum':   return rows.reduce((acc, r) => acc + (Number(r[aggregateField]) || 0), 0);
-            case 'avg':   return rows.reduce((acc, r) => acc + (Number(r[aggregateField]) || 0), 0) / rows.length;
-            case 'min':   return rows.reduce((m, r) => (r[aggregateField] < m ? r[aggregateField] : m), rows[0][aggregateField]);
-            case 'max':   return rows.reduce((m, r) => (r[aggregateField] > m ? r[aggregateField] : m), rows[0][aggregateField]);
-            case 'count': return rows.length;
-            default:      return null;
-        }
-    }
-
-    // -- Redis-Specific Operations ------------------------
-
-    /**
-     * Get a value by key (raw Redis GET).
-     * @param {string} key - Cache or storage key.
-     * @returns {Promise<string|null>} Stored value, or `null` if not found.
-     */
-    async get(key)
-    {
-        this._validateKey(key);
-        return this._client.get(this._prefix + key);
-    }
-
-    /**
-     * Set a key-value pair (raw Redis SET).
-     * @param {string} key - Cache or storage key.
-     * @param {*} value - Value to set.
-     * @param {number} [ttl] - Optional TTL in seconds.
-     * @returns {Promise<string>} Redis `"OK"` response.
-     */
-    async set(key, value, ttl)
-    {
-        this._validateKey(key);
-        if (ttl !== undefined && (!Number.isFinite(ttl) || ttl < 0))
-            throw new Error('Redis: TTL must be a non-negative number');
-        const k = this._prefix + key;
-        const v = typeof value === 'object' ? JSON.stringify(value) : String(value);
-        if (ttl) return this._client.setex(k, ttl, v);
-        return this._client.set(k, v);
-    }
-
-    /**
-     * Delete a key.
-     * @param {string} key - Cache or storage key.
-     * @returns {Promise<number>} Number of keys deleted (0 or 1).
-     */
-    async del(key)
-    {
-        this._validateKey(key);
-        return this._client.del(this._prefix + key);
-    }
-
-    /**
-     * Check if a key exists.
-     * @param {string} key - Cache or storage key.
-     * @returns {Promise<boolean>} `true` if the key exists.
-     */
-    async exists(key)
-    {
-        this._validateKey(key);
-        return (await this._client.exists(this._prefix + key)) === 1;
-    }
-
-    /**
-     * Set expiration on a key.
-     * @param {string} key - Cache or storage key.
-     * @param {number} seconds - Time in seconds.
-     * @returns {Promise<number>} `1` if timeout was set, `0` if key does not exist.
-     */
-    async expire(key, seconds)
-    {
-        this._validateKey(key);
-        if (!Number.isFinite(seconds) || seconds < 0)
-            throw new Error('Redis: TTL must be a non-negative number');
-        return this._client.expire(this._prefix + key, seconds);
-    }
-
-    /**
-     * Get TTL of a key in seconds.
-     * @param {string} key - Cache or storage key.
-     * @returns {Promise<number>} -1 if no expiry, -2 if key doesn't exist.
-     */
-    async ttl(key)
-    {
-        this._validateKey(key);
-        return this._client.ttl(this._prefix + key);
-    }
-
-    /**
-     * Increment a numeric key.
-     * @param {string} key - Cache or storage key.
-     * @param {number} [by=1] - Increment step.
-     * @returns {Promise<number>} Value after increment.
-     */
-    async incr(key, by = 1)
-    {
-        this._validateKey(key);
-        if (by === 1) return this._client.incr(this._prefix + key);
-        return this._client.incrby(this._prefix + key, by);
-    }
-
-    /**
-     * Decrement a numeric key.
-     * @param {string} key - Cache or storage key.
-     * @param {number} [by=1] - Increment step.
-     * @returns {Promise<number>} Value after decrement.
-     */
-    async decr(key, by = 1)
-    {
-        this._validateKey(key);
-        if (by === 1) return this._client.decr(this._prefix + key);
-        return this._client.decrby(this._prefix + key, by);
-    }
-
-    // -- Hash Operations ----------------------------------
-
-    /**
-     * Set a hash field.
-     * @param {string} key - Cache or storage key.
-     * @param {string} field - Field name.
-     * @param {*} value - Value to set.
-     * @returns {Promise<number>} `1` if field is new, `0` if updated.
-     */
-    async hset(key, field, value)
-    {
-        this._validateKey(key);
-        return this._client.hset(this._prefix + key, field, typeof value === 'object' ? JSON.stringify(value) : String(value));
-    }
-
-    /**
-     * Get a hash field.
-     * @param {string} key - Cache or storage key.
-     * @param {string} field - Field name.
-     * @returns {Promise<string|null>} Field value, or `null` if not found.
-     */
-    async hget(key, field)
-    {
-        this._validateKey(key);
-        return this._client.hget(this._prefix + key, field);
-    }
-
-    /**
-     * Get all fields in a hash.
-     * @param {string} key - Cache or storage key.
-     * @returns {Promise<object>} Object of field-value pairs.
-     */
-    async hgetall(key)
-    {
-        this._validateKey(key);
-        return this._client.hgetall(this._prefix + key);
-    }
-
-    /**
-     * Delete a hash field.
-     * @param {string} key - Cache or storage key.
-     * @param {string} field - Field name.
-     * @returns {Promise<number>} `1` if the field was removed, `0` if it did not exist.
-     */
-    async hdel(key, field)
-    {
-        this._validateKey(key);
-        return this._client.hdel(this._prefix + key, field);
-    }
-
-    // -- List Operations ----------------------------------
-
-    /**
-     * Push values to the end of a list.
-     * @param {string} key - Cache or storage key.
-     * @param {...*} values - Array of values.
-     * @returns {Promise<number>} Length of list after push.
-     */
-    async rpush(key, ...values)
-    {
-        this._validateKey(key);
-        return this._client.rpush(this._prefix + key, ...values.map(v => typeof v === 'object' ? JSON.stringify(v) : String(v)));
-    }
-
-    /**
-     * Push values to the beginning of a list.
-     * @param {string} key - Cache or storage key.
-     * @param {...*} values - Array of values.
-     * @returns {Promise<number>} Length of list after push.
-     */
-    async lpush(key, ...values)
-    {
-        this._validateKey(key);
-        return this._client.lpush(this._prefix + key, ...values.map(v => typeof v === 'object' ? JSON.stringify(v) : String(v)));
-    }
-
-    /**
-     * Get a range of list elements.
-     * @param {string} key - Cache or storage key.
-     * @param {number} [start=0] - Start offset.
-     * @param {number} [stop=-1] - Stop offset.
-     * @returns {Promise<string[]>} Array of list elements.
-     */
-    async lrange(key, start = 0, stop = -1)
-    {
-        this._validateKey(key);
-        return this._client.lrange(this._prefix + key, start, stop);
-    }
-
-    /**
-     * Pop from the end of a list.
-     * @param {string} key - Cache or storage key.
-     * @returns {Promise<string|null>} Removed element, or `null` if empty.
-     */
-    async rpop(key)
-    {
-        this._validateKey(key);
-        return this._client.rpop(this._prefix + key);
-    }
-
-    /**
-     * Pop from the beginning of a list.
-     * @param {string} key - Cache or storage key.
-     * @returns {Promise<string|null>} Removed element, or `null` if empty.
-     */
-    async lpop(key)
-    {
-        this._validateKey(key);
-        return this._client.lpop(this._prefix + key);
-    }
-
-    /**
-     * Get list length.
-     * @param {string} key - Cache or storage key.
-     * @returns {Promise<number>} Number of elements in the list.
-     */
-    async llen(key)
-    {
-        this._validateKey(key);
-        return this._client.llen(this._prefix + key);
-    }
-
-    // -- Set Operations -----------------------------------
-
-    /**
-     * Add members to a set.
-     * @param {string} key - Cache or storage key.
-     * @param {...*} members - Array of set members.
-     * @returns {Promise<number>} Number of members actually added.
-     */
-    async sadd(key, ...members)
-    {
-        this._validateKey(key);
-        return this._client.sadd(this._prefix + key, ...members.map(String));
-    }
-
-    /**
-     * Get all members of a set.
-     * @param {string} key - Cache or storage key.
-     * @returns {Promise<string[]>} Array of set members.
-     */
-    async smembers(key)
-    {
-        this._validateKey(key);
-        return this._client.smembers(this._prefix + key);
-    }
-
-    /**
-     * Check if a value is a member of a set.
-     * @param {string} key - Cache or storage key.
-     * @param {*} member - Set member.
-     * @returns {Promise<boolean>} `true` if the value is a member.
-     */
-    async sismember(key, member)
-    {
-        this._validateKey(key);
-        return (await this._client.sismember(this._prefix + key, String(member))) === 1;
-    }
-
-    /**
-     * Remove a member from a set.
-     * @param {string} key - Cache or storage key.
-     * @param {*} member - Set member.
-     * @returns {Promise<number>} `1` if the member was removed, `0` otherwise.
-     */
-    async srem(key, member)
-    {
-        this._validateKey(key);
-        return this._client.srem(this._prefix + key, String(member));
-    }
-
-    /**
-     * Get the number of members in a set.
-     * @param {string} key - Cache or storage key.
-     * @returns {Promise<number>} Number of members in the set.
-     */
-    async scard(key)
-    {
-        this._validateKey(key);
-        return this._client.scard(this._prefix + key);
-    }
-
-    // -- Sorted Set Operations ----------------------------
-
-    /**
-     * Add a member to a sorted set.
-     * @param {string} key - Cache or storage key.
-     * @param {number} score - Sort score.
-     * @param {*} member - Set member.
-     * @returns {Promise<number>} Number of members actually added.
-     */
-    async zadd(key, score, member)
-    {
-        this._validateKey(key);
-        return this._client.zadd(this._prefix + key, score, String(member));
-    }
-
-    /**
-     * Get members from a sorted set by score range.
-     * @param {string} key - Cache or storage key.
-     * @param {number|string} min - Minimum value.
-     * @param {number|string} max - Maximum value.
-     * @returns {Promise<string[]>} Array of matching members.
-     */
-    async zrangebyscore(key, min, max)
-    {
-        this._validateKey(key);
-        return this._client.zrangebyscore(this._prefix + key, min, max);
-    }
-
-    /**
-     * Get members from a sorted set by rank range.
-     * @param {string} key - Cache or storage key.
-     * @param {number} start - Start offset.
-     * @param {number} stop - Stop offset.
-     * @returns {Promise<string[]>} Array of members in rank order.
-     */
-    async zrange(key, start, stop)
-    {
-        this._validateKey(key);
-        return this._client.zrange(this._prefix + key, start, stop);
-    }
-
-    /**
-     * Remove a member from a sorted set.
-     * @param {string} key - Cache or storage key.
-     * @param {*} member - Set member.
-     * @returns {Promise<number>} Number of members removed.
-     */
-    async zrem(key, member)
-    {
-        this._validateKey(key);
-        return this._client.zrem(this._prefix + key, String(member));
-    }
-
-    /**
-     * Get sorted set cardinality.
-     * @param {string} key - Cache or storage key.
-     * @returns {Promise<number>} Number of members in the sorted set.
-     */
-    async zcard(key)
-    {
-        this._validateKey(key);
-        return this._client.zcard(this._prefix + key);
-    }
-
-    // -- Pub/Sub ------------------------------------------
-
-    /**
-     * Subscribe to a channel.
-     * @param {string} channel - Channel name.
-     * @param {Function} callback - Called with (message, channel).
-     * @returns {Promise<Function>} Unsubscribe function.
-     */
-    async subscribe(channel, callback)
-    {
-        this._validateKey(channel, 'channel');
-        if (typeof callback !== 'function')
-            throw new Error('Redis: subscribe callback must be a function');
-        if (!this._subClient)
-        {
-            this._subClient = this._client.duplicate();
-        }
-
-        const prefixedChannel = this._prefix + channel;
-        await this._subClient.subscribe(prefixedChannel);
-
-        const handler = (ch, message) =>
-        {
-            if (ch === prefixedChannel) callback(message, channel);
-        };
-        this._subClient.on('message', handler);
-
-        if (!this._subscribers.has(prefixedChannel))
-        {
-            this._subscribers.set(prefixedChannel, []);
-        }
-        this._subscribers.get(prefixedChannel).push({ callback, handler });
-
-        // Return unsubscribe function
-        return async () =>
-        {
-            this._subClient.removeListener('message', handler);
-            const subs = this._subscribers.get(prefixedChannel) || [];
-            const idx = subs.findIndex(s => s.callback === callback);
-            if (idx !== -1) subs.splice(idx, 1);
-            if (subs.length === 0)
-            {
-                await this._subClient.unsubscribe(prefixedChannel);
-                this._subscribers.delete(prefixedChannel);
-            }
-        };
-    }
-
-    /**
-     * Publish a message to a channel.
-     * @param {string} channel - Channel name.
-     * @param {*} message - Message payload.
-     * @returns {Promise<number>} Number of subscribers that received the message.
-     */
-    async publish(channel, message)
-    {
-        this._validateKey(channel, 'channel');
-        const msg = typeof message === 'object' ? JSON.stringify(message) : String(message);
-        return this._client.publish(this._prefix + channel, msg);
-    }
-
-    // -- Pipeline / Batch ---------------------------------
-
-    /**
-     * Create a pipeline for batching commands.
-     * @returns {Pipeline} Prefixed pipeline wrapper.
-     *
-     * @example
-     *   const pipe = adapter.pipeline();
-     *   pipe.set('key1', 'val1');
-     *   pipe.set('key2', 'val2');
-     *   const results = await pipe.exec();
-     */
-    pipeline()
-    {
-        const pipe = this._client.pipeline();
-        const adapter = this;
-
-        // Wrap to add prefix
-        return {
-            set(key, value, ...args)
-            {
-                pipe.set(adapter._prefix + key, typeof value === 'object' ? JSON.stringify(value) : String(value), ...args);
-                return this;
-            },
-            get(key) { pipe.get(adapter._prefix + key); return this; },
-            del(key) { pipe.del(adapter._prefix + key); return this; },
-            hset(key, field, value)
-            {
-                pipe.hset(adapter._prefix + key, field, typeof value === 'object' ? JSON.stringify(value) : String(value));
-                return this;
-            },
-            hget(key, field) { pipe.hget(adapter._prefix + key, field); return this; },
-            incr(key) { pipe.incr(adapter._prefix + key); return this; },
-            decr(key) { pipe.decr(adapter._prefix + key); return this; },
-            expire(key, seconds) { pipe.expire(adapter._prefix + key, seconds); return this; },
-            sadd(key, ...members) { pipe.sadd(adapter._prefix + key, ...members.map(String)); return this; },
-            rpush(key, ...values) { pipe.rpush(adapter._prefix + key, ...values.map(v => typeof v === 'object' ? JSON.stringify(v) : String(v))); return this; },
-            async exec() { return pipe.exec(); },
-        };
-    }
-
-    // -- Transaction Support ------------------------------
-
-    /**
-     * Begin a Redis MULTI transaction.
-     */
-    async beginTransaction()
-    {
-        this._multi = this._client.multi();
-    }
-
-    /**
-     * Commit a MULTI transaction.
-     */
-    async commit()
-    {
-        if (this._multi)
-        {
-            await this._multi.exec();
-            this._multi = null;
-        }
-    }
-
-    /**
-     * Discard a MULTI transaction.
-     */
-    async rollback()
-    {
-        if (this._multi)
-        {
-            this._multi.discard();
-            this._multi = null;
-        }
-    }
-
-    // -- Utility & Admin ----------------------------------
-
-    /**
-     * Clear all data (flush matched prefix keys).
-     * Uses SCAN for safety in production (no KEYS *).
-     */
-    async clear()
-    {
-        let cursor = '0';
-        do
-        {
-            const [nextCursor, keys] = await this._client.scan(cursor, 'MATCH', this._prefix + '*', 'COUNT', 100);
-            cursor = nextCursor;
-            if (keys.length > 0)
-            {
-                await this._client.del(...keys);
-            }
-        } while (cursor !== '0');
-    }
-
-    /**
-     * Ping the Redis server.
-     * @returns {Promise<boolean>} `true` if the server responds.
-     */
-    async ping()
-    {
-        try
-        {
-            const result = await this._client.ping();
-            return result === 'PONG';
-        }
-        catch (_)
-        {
-            return false;
-        }
-    }
-
-    /**
-     * Get Redis server info.
-     * @param {string} [section] - Optional section (e.g., 'memory', 'clients', 'stats').
-     * @returns {Promise<string>} Raw Redis INFO output.
-     */
-    async info(section)
-    {
-        return section ? this._client.info(section) : this._client.info();
-    }
-
-    /**
-     * Get database size (number of keys).
-     * @returns {Promise<number>} Total number of keys in the database.
-     */
-    async dbsize()
-    {
-        return this._client.dbsize();
-    }
-
-    /**
-     * List all table names (by scanning for schema keys).
-     * @returns {Promise<string[]>} Array of table names.
-     */
-    async tables()
-    {
-        const tables = [];
-        let cursor = '0';
-        const pattern = this._prefix + '*:_schema';
-        do
-        {
-            const [nextCursor, keys] = await this._client.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
-            cursor = nextCursor;
-            for (const key of keys)
-            {
-                // Extract table name: zh:users:_schema → users
-                const stripped = key.slice(this._prefix.length);
-                const table = stripped.replace(/:_schema$/, '');
-                tables.push(table);
-            }
-        } while (cursor !== '0');
-        return tables;
-    }
-
-    /**
-     * Get stats for the adapter.
-     * @returns {Promise<object>} Adapter statistics.
-     */
-    async stats()
-    {
-        const tableNames = await this.tables();
-        let totalRows = 0;
-        for (const t of tableNames)
-        {
-            totalRows += await this._client.zcard(this._idsKey(t));
-        }
-        return {
-            tables: tableNames.length,
-            totalRows,
-            dbsize: await this._client.dbsize(),
-            prefix: this._prefix,
-        };
-    }
-
-    /**
-     * Get pool/connection status.
-     * @returns {{ status: string, prefix: string }}
-     */
-    poolStatus()
-    {
-        return {
-            status: this._client.status,
-            prefix: this._prefix,
-        };
-    }
-
-    /**
-     * Get the underlying ioredis client.
-     * @returns {object} The ioredis client instance.
-     */
-    get client()
-    {
-        return this._client;
-    }
-
-    /**
-     * Execute a raw Redis command.
-     * @param {string} command - Command name.
-     * @param {...*} args - Command arguments.
-     * @returns {Promise<*>} Command result.
-     */
-    async raw(command, ...args)
-    {
-        if (typeof command !== 'string' || command.length === 0)
-            throw new Error('Redis: command must be a non-empty string');
-        return this._client.call(command, ...args);
-    }
-
-    /**
-     * Close the connection.
-     */
-    async close()
-    {
-        if (this._subClient)
-        {
-            await this._subClient.quit();
-            this._subClient = null;
-        }
-        await this._client.quit();
-    }
-
-    // -- Migration / DDL Methods --------------------------
-
-    /**
-     * Add a column to an existing table.
-     * @param {string} table - Table name.
-     * @param {string} column - Column name.
-     * @param {object} def - Column definition.
-     */
-    async addColumn(table, column, def)
-    {
-        const schema = this._schemas.get(table);
-        if (schema) schema[column] = def;
-
-        const defaultVal = def.default !== undefined
-            ? (typeof def.default === 'function' ? def.default() : def.default)
-            : null;
-
-        // Update all existing rows
-        const rows = await this._getAllRows(table);
-        const pipeline = this._client.pipeline();
-        for (const row of rows)
-        {
-            if (row[column] === undefined)
-            {
-                row[column] = defaultVal;
-                pipeline.set(this._rowKey(table, row.id), this._serialize(row));
-            }
-        }
-        if (rows.length > 0) await pipeline.exec();
-
-        // Update stored schema
-        await this._client.set(this._schemaKey(table), JSON.stringify(this._schemas.get(table) || {}));
-    }
-
-    /**
-     * Drop a column from a table.
-     * @param {string} table - Table name.
-     * @param {string} column - Column name.
-     */
-    async dropColumn(table, column)
-    {
-        const schema = this._schemas.get(table);
-        if (schema) delete schema[column];
-
-        const rows = await this._getAllRows(table);
-        const pipeline = this._client.pipeline();
-        for (const row of rows)
-        {
-            delete row[column];
-            pipeline.set(this._rowKey(table, row.id), this._serialize(row));
-        }
-        if (rows.length > 0) await pipeline.exec();
-    }
-
-    /**
-     * Rename a column.
-     * @param {string} table - Table name.
-     * @param {string} oldName - Current name.
-     * @param {string} newName - New name.
-     */
-    async renameColumn(table, oldName, newName)
-    {
-        const schema = this._schemas.get(table);
-        if (schema && schema[oldName])
-        {
-            schema[newName] = schema[oldName];
-            delete schema[oldName];
-        }
-
-        const rows = await this._getAllRows(table);
-        const pipeline = this._client.pipeline();
-        for (const row of rows)
-        {
-            if (oldName in row)
-            {
-                row[newName] = row[oldName];
-                delete row[oldName];
-                pipeline.set(this._rowKey(table, row.id), this._serialize(row));
-            }
-        }
-        if (rows.length > 0) await pipeline.exec();
-    }
-
-    /**
-     * Rename a table.
-     * @param {string} oldName - Current name.
-     * @param {string} newName - New name.
-     */
-    async renameTable(oldName, newName)
-    {
-        const rows = await this._getAllRows(oldName);
-
-        // Create new table with all rows
-        const schema = this._schemas.get(oldName);
-        if (schema)
-        {
-            this._schemas.set(newName, schema);
-            this._schemas.delete(oldName);
-        }
-
-        const pipeline = this._client.pipeline();
-
-        // Copy sequence
-        const seq = await this._client.get(this._seqKey(oldName));
-        pipeline.set(this._seqKey(newName), seq || '0');
-
-        // Copy rows to new keys
-        for (const row of rows)
-        {
-            pipeline.set(this._rowKey(newName, row.id), this._serialize(row));
-            pipeline.zadd(this._idsKey(newName), Number(row.id) || 0, String(row.id));
-        }
-
-        // Store new schema
-        if (schema)
-        {
-            pipeline.set(this._schemaKey(newName), JSON.stringify(schema));
-        }
-
-        await pipeline.exec();
-
-        // Drop old table
-        await this.dropTable(oldName);
-    }
-
-    /**
-     * Create an index (tracked in metadata).
-     * @param {string} table - Table name.
-     * @param {string|string[]} columns - Column name(s).
-     * @param {{ name?: string, unique?: boolean }} [options={}]
-     */
-    async createIndex(table, columns, options = {})
-    {
-        const cols = Array.isArray(columns) ? columns : [columns];
-        const name = options.name || `idx_${table}_${cols.join('_')}`;
-        if (!this._indexes.has(table)) this._indexes.set(table, []);
-        this._indexes.get(table).push({ name, columns: cols, unique: !!options.unique });
-    }
-
-    /**
-     * Drop an index.
-     * @param {string} _table - Table name (unused).
-     * @param {string} name - Name identifier.
-     */
-    async dropIndex(_table, name)
-    {
-        for (const [, indexes] of this._indexes)
-        {
-            const idx = indexes.findIndex(i => i.name === name);
-            if (idx !== -1) { indexes.splice(idx, 1); return; }
-        }
-    }
-
-    /**
-     * Check if a table exists.
-     * @param {string} table - Table name.
-     * @returns {Promise<boolean>} `true` if the table exists.
-     */
-    async hasTable(table)
-    {
-        return (await this._client.exists(this._seqKey(table))) === 1 ||
-               (await this._client.exists(this._schemaKey(table))) === 1;
-    }
-
-    /**
-     * Check if a column exists on a table.
-     * @param {string} table - Table name.
-     * @param {string} column - Column name.
-     * @returns {Promise<boolean>} `true` if the column exists.
-     */
-    async hasColumn(table, column)
-    {
-        const schema = this._schemas.get(table);
-        if (schema) return column in schema;
-        // Check first row
-        const ids = await this._client.zrange(this._idsKey(table), 0, 0);
-        if (ids.length === 0) return false;
-        const row = this._deserialize(await this._client.get(this._rowKey(table, ids[0])));
-        return row ? column in row : false;
-    }
-
-    /**
-     * Describe a table's columns.
-     * @param {string} table - Table name.
-     * @returns {Promise<Array>} Array of column definitions.
-     */
-    async describeTable(table)
-    {
-        const schema = this._schemas.get(table);
-        if (!schema) return [];
-        return Object.entries(schema).map(([name, def]) => ({
-            name,
-            type: def.type || 'TEXT',
-            nullable: !def.required,
-            defaultValue: def.default !== undefined ? def.default : null,
-            primaryKey: !!def.primaryKey,
-        }));
-    }
-
-    /**
-     * Get indexes for a table.
-     * @param {string} table - Table name.
-     * @returns {Promise<Array>} Array of index definitions.
-     */
-    async indexes(table)
-    {
-        return this._indexes.get(table) || [];
-    }
-
-    // -- Internal Helpers ---------------------------------
-
-    /**
-     * Get all rows for a table.
-     * @private
-     * @param {string} table - Table name.
-     * @returns {Promise<object[]>} All rows in the table.
-     */
-    async _getAllRows(table)
-    {
-        const ids = await this._client.zrange(this._idsKey(table), 0, -1);
-        if (ids.length === 0) return [];
-
-        const pipeline = this._client.pipeline();
-        for (const id of ids)
-        {
-            pipeline.get(this._rowKey(table, id));
-        }
-        const results = await pipeline.exec();
-        const rows = [];
-        for (const [err, val] of results)
-        {
-            if (!err && val)
-            {
-                const row = this._deserialize(val);
-                if (row) rows.push(row);
-            }
-        }
-        return rows;
-    }
-
-    /** @private Match simple conditions. */
-    _matchConditions(row, conditions)
-    {
-        if (!conditions || typeof conditions !== 'object') return true;
-        for (const [k, v] of Object.entries(conditions))
-        {
-            if (row[k] !== v) return false;
-        }
-        return true;
-    }
-
-    /** @private Apply the where chain from query builder. */
-    _applyWhereChain(row, where)
-    {
-        let result = true;
-        for (let i = 0; i < where.length; i++)
-        {
-            const clause = where[i];
-            if (clause.raw) continue;
-            const matches = this._matchClause(row, clause);
-
-            if (i === 0 || clause.logic === 'AND')
-            {
-                result = i === 0 ? matches : (result && matches);
-            }
-            else if (clause.logic === 'OR')
-            {
-                result = result || matches;
-            }
-        }
-        return result;
-    }
-
-    /** @private Match a single WHERE clause. */
-    _matchClause(row, clause)
-    {
-        const val = row[clause.field];
-        const { op, value } = clause;
-
-        switch (op)
-        {
-            case '=':           return val === value;
-            case '!=':
-            case '<>':          return val !== value;
-            case '>':           return val > value;
-            case '<':           return val < value;
-            case '>=':          return val >= value;
-            case '<=':          return val <= value;
-            case 'LIKE':        return _likeSafe(String(val), String(value));
-            case 'IN':          return Array.isArray(value) && value.includes(val);
-            case 'NOT IN':      return Array.isArray(value) && !value.includes(val);
-            case 'BETWEEN':     return Array.isArray(value) && val >= value[0] && val <= value[1];
-            case 'NOT BETWEEN': return Array.isArray(value) && (val < value[0] || val > value[1]);
-            case 'IS NULL':     return val === null || val === undefined;
-            case 'IS NOT NULL':  return val !== null && val !== undefined;
-            default:            return val === value;
-        }
-    }
-
-    /** @private Compare for HAVING. */
-    _compareOp(actual, op, value)
-    {
-        switch (op.toUpperCase())
-        {
-            case '=':  return actual === value;
-            case '!=':
-            case '<>': return actual !== value;
-            case '>':  return actual > value;
-            case '<':  return actual < value;
-            case '>=': return actual >= value;
-            case '<=': return actual <= value;
-            default:   return actual === value;
-        }
-    }
-
-    /** @private Enforce unique constraints. */
-    async _enforceUnique(table, row, excludeRow)
-    {
-        const schema = this._schemas.get(table);
-        if (!schema) return;
-
-        const rows = await this._getAllRows(table);
-
-        for (const [col, def] of Object.entries(schema))
-        {
-            if (def.unique && row[col] !== undefined && row[col] !== null)
-            {
-                const duplicate = rows.find(r =>
-                    r !== excludeRow && r.id !== (excludeRow && excludeRow.id) && r[col] === row[col]
-                );
-                if (duplicate)
-                {
-                    throw new Error(`UNIQUE constraint failed: ${table}.${col}`);
-                }
-            }
-        }
-
-        // Composite unique
-        const groups = {};
-        for (const [col, def] of Object.entries(schema))
-        {
-            if (def.compositeUnique)
-            {
-                const g = typeof def.compositeUnique === 'string' ? def.compositeUnique : 'default';
-                if (!groups[g]) groups[g] = [];
-                groups[g].push(col);
-            }
-        }
-        for (const cols of Object.values(groups))
-        {
-            const duplicate = rows.find(r =>
-                r !== excludeRow && r.id !== (excludeRow && excludeRow.id) && cols.every(c => r[c] === row[c])
-            );
-            if (duplicate)
-            {
-                throw new Error(`UNIQUE constraint failed: ${table}.(${cols.join(', ')})`);
-            }
-        }
-    }
-}
-
-module.exports = RedisAdapter;
+/**
+ * @module orm/adapters/redis
+ * @description Redis database adapter for the zero-server ORM.
+ *              Uses `ioredis` as the driver. Stores table data as Redis hashes
+ *              with sorted-set indexes for ordering and filtering.
+ *
+ *              Bring-your-own-driver: `npm install ioredis`
+ *
+ *              Supports full ORM CRUD, key-value operations, pub/sub,
+ *              pipelines, TTL, and all DDL/migration methods.
+ *
+ * @example
+ *   // Connect by host/port
+ *   const db = Database.connect('redis', { host: '127.0.0.1', port: 6379 });
+ *
+ *   // Connect by URL with authentication
+ *   const db2 = Database.connect('redis', { url: 'redis://user:pass@host:6379/0' });
+ *
+ *   // Connect with key prefix
+ *   const db3 = Database.connect('redis', { url: 'redis://host:6379', prefix: 'myapp:' });
+ */
+
+let Redis;
+try { Redis = require('ioredis'); } catch (_) { /* loaded lazily */ }
+
+/**
+ * ReDoS-safe SQL LIKE matcher using iterative DP.
+ * % = any sequence of chars, _ = any single char. Case-insensitive.
+ * @private
+ */
+function _likeSafe(str, pattern)
+{
+    const s = str.toLowerCase();
+    const p = pattern.toLowerCase();
+    const sLen = s.length, pLen = p.length;
+    let dp = new Array(pLen + 1).fill(false);
+    dp[0] = true;
+    for (let j = 0; j < pLen; j++) { if (p[j] === '%') dp[j + 1] = dp[j]; }
+    for (let i = 1; i <= sLen; i++)
+    {
+        const next = new Array(pLen + 1).fill(false);
+        for (let j = 1; j <= pLen; j++)
+        {
+            if (p[j - 1] === '%')       next[j] = dp[j] || next[j - 1];
+            else if (p[j - 1] === '_')  next[j] = dp[j - 1];
+            else                        next[j] = dp[j - 1] && s[i - 1] === p[j - 1];
+        }
+        dp = next;
+    }
+    return dp[pLen];
+}
+
+class RedisAdapter
+{
+    /**
+     * @constructor
+     * @param {object} [options] - Configuration options.
+     * @param {string} [options.url]             - Redis connection URL.
+     * @param {string} [options.host='127.0.0.1'] - Redis host.
+     * @param {number} [options.port=6379]       - Redis port.
+     * @param {string} [options.password]        - Redis password.
+     * @param {number} [options.db=0]            - Redis database index.
+     * @param {string} [options.prefix='zh:']    - Key prefix for namespacing.
+     * @param {number} [options.maxRetries=3]    - Max connection retries.
+     * @param {boolean} [options.lazyConnect=false] - If true, defer connection until first operation.
+     * @param {object} [options.tls]             - TLS options for secure connections.
+     * @param {string} [options.keyPrefix]       - Alias for prefix (ioredis compat).
+     * @param {number} [options.connectTimeout=10000] - Connection timeout in ms.
+     */
+    constructor(options = {})
+    {
+        if (!Redis)
+        {
+            throw new Error(
+                'Redis adapter requires the "ioredis" package.\n' +
+                'Install it with: npm install ioredis'
+            );
+        }
+
+        // Validate options at the boundary
+        if (options.host !== undefined && (typeof options.host !== 'string' || !options.host.length))
+            throw new Error('Redis: host must be a non-empty string');
+        if (options.port !== undefined)
+        {
+            const p = Number(options.port);
+            if (!Number.isInteger(p) || p < 1 || p > 65535)
+                throw new Error('Redis: port must be an integer between 1 and 65535');
+        }
+        if (options.db !== undefined)
+        {
+            const d = Number(options.db);
+            if (!Number.isInteger(d) || d < 0 || d > 15)
+                throw new Error('Redis: db must be an integer between 0 and 15');
+        }
+        if (options.password !== undefined && typeof options.password !== 'string')
+            throw new Error('Redis: password must be a string');
+        if (options.url !== undefined && typeof options.url !== 'string')
+            throw new Error('Redis: url must be a string');
+        if (options.prefix !== undefined && typeof options.prefix !== 'string')
+            throw new Error('Redis: prefix must be a string');
+        if (options.connectTimeout !== undefined)
+        {
+            const ct = Number(options.connectTimeout);
+            if (!Number.isFinite(ct) || ct < 0)
+                throw new Error('Redis: connectTimeout must be a non-negative number');
+        }
+
+        this._prefix = options.prefix || options.keyPrefix || 'zh:';
+        this._schemas = new Map();
+        this._indexes = new Map();
+        this._subscribers = new Map();
+
+        // Build ioredis config
+        const config = {};
+        if (options.url)
+        {
+            this._client = new Redis(options.url, {
+                maxRetriesPerRequest: options.maxRetries || 3,
+                lazyConnect: options.lazyConnect || false,
+                connectTimeout: options.connectTimeout || 10000,
+                tls: options.tls,
+                keyPrefix: undefined, // we manage prefix ourselves
+            });
+        }
+        else
+        {
+            config.host = options.host || '127.0.0.1';
+            config.port = options.port || 6379;
+            if (options.password) config.password = options.password;
+            if (options.db !== undefined) config.db = options.db;
+            config.maxRetriesPerRequest = options.maxRetries || 3;
+            config.lazyConnect = options.lazyConnect || false;
+            config.connectTimeout = options.connectTimeout || 10000;
+            if (options.tls) config.tls = options.tls;
+
+            this._client = new Redis(config);
+        }
+
+        // Separate client for pub/sub (subscribers block the connection)
+        this._subClient = null;
+    }
+
+    // -- Key Helpers --------------------------------------
+
+    /** @private Validate a table name or key to prevent internal key collision. */
+    _validateKey(key, label = 'key')
+    {
+        if (typeof key !== 'string' || key.length === 0)
+            throw new Error(`Redis: ${label} must be a non-empty string`);
+        if (/[\x00-\x1f]/.test(key))
+            throw new Error(`Redis: ${label} must not contain control characters`);
+    }
+
+    /** @private Build a prefixed key for a table's metadata. */
+    _key(table, ...parts)
+    {
+        return this._prefix + table + (parts.length ? ':' + parts.join(':') : '');
+    }
+
+    /** @private Key for a table's row hash: zh:users:row:42 */
+    _rowKey(table, id)
+    {
+        return this._key(table, 'row', String(id));
+    }
+
+    /** @private Key for a table's ID index sorted set: zh:users:_ids */
+    _idsKey(table)
+    {
+        return this._key(table, '_ids');
+    }
+
+    /** @private Key for a table's auto-increment counter: zh:users:_seq */
+    _seqKey(table)
+    {
+        return this._key(table, '_seq');
+    }
+
+    /** @private Key for a table's schema definition: zh:users:_schema */
+    _schemaKey(table)
+    {
+        return this._key(table, '_schema');
+    }
+
+    /** @private Serialize a row for storage. */
+    _serialize(row)
+    {
+        return JSON.stringify(row);
+    }
+
+    /** @private Deserialize a stored row. */
+    _deserialize(data)
+    {
+        if (data === null || data === undefined) return null;
+        try { return JSON.parse(data); }
+        catch (_) { return null; }
+    }
+
+    // -- Table Management ---------------------------------
+
+    /**
+     * Create a table (register schema + initialize index).
+     * @param {string} table - Table name.
+     * @param {object} [schema] - Schema definition.
+     */
+    async createTable(table, schema)
+    {
+        this._validateKey(table, 'table name');
+        if (schema)
+        {
+            this._schemas.set(table, schema);
+            await this._client.set(this._schemaKey(table), JSON.stringify(schema));
+        }
+        // Ensure the sequence key exists
+        const exists = await this._client.exists(this._seqKey(table));
+        if (!exists) await this._client.set(this._seqKey(table), '0');
+    }
+
+    /**
+     * Drop a table (delete all keys).
+     * @param {string} table - Table name.
+     */
+    async dropTable(table)
+    {
+        // Get all row IDs
+        const ids = await this._client.zrange(this._idsKey(table), 0, -1);
+        const pipeline = this._client.pipeline();
+
+        for (const id of ids)
+        {
+            pipeline.del(this._rowKey(table, id));
+        }
+        pipeline.del(this._idsKey(table));
+        pipeline.del(this._seqKey(table));
+        pipeline.del(this._schemaKey(table));
+
+        // Delete any field index keys
+        const schema = this._schemas.get(table);
+        if (schema)
+        {
+            for (const col of Object.keys(schema))
+            {
+                pipeline.del(this._key(table, 'idx', col));
+            }
+        }
+
+        await pipeline.exec();
+        this._schemas.delete(table);
+        this._indexes.delete(table);
+    }
+
+    // -- CRUD Operations ----------------------------------
+
+    /**
+     * Insert a row.
+     * @param {string} table - Table name.
+     * @param {object} data - Record data object.
+     * @returns {Promise<object>} Inserted row with ID.
+     */
+    async insert(table, data)
+    {
+        const row = { ...data };
+
+        // Auto-increment if no ID provided
+        if (row.id === undefined || row.id === null)
+        {
+            row.id = await this._client.incr(this._seqKey(table));
+        }
+        else
+        {
+            // Ensure sequence is ahead of manual IDs
+            const current = parseInt(await this._client.get(this._seqKey(table)) || '0', 10);
+            if (typeof row.id === 'number' && row.id >= current)
+            {
+                await this._client.set(this._seqKey(table), String(row.id + 1));
+            }
+        }
+
+        // Serialize dates
+        for (const [k, v] of Object.entries(row))
+        {
+            if (v instanceof Date) row[k] = v.toISOString();
+        }
+
+        // Enforce unique constraints
+        await this._enforceUnique(table, row);
+
+        // Store the row as a JSON string
+        const pipeline = this._client.pipeline();
+        pipeline.set(this._rowKey(table, row.id), this._serialize(row));
+        // Add to sorted set index (score = numeric id for ordering)
+        pipeline.zadd(this._idsKey(table), Number(row.id) || 0, String(row.id));
+
+        await pipeline.exec();
+
+        return row;
+    }
+
+    /**
+     * Insert multiple rows.
+     * @param {string} table - Table name.
+     * @param {object[]} dataArray - Array of record objects.
+     * @returns {Promise<object[]>} Array of inserted rows.
+     */
+    async insertMany(table, dataArray)
+    {
+        const results = [];
+        for (const data of dataArray) results.push(await this.insert(table, data));
+        return results;
+    }
+
+    /**
+     * Update a row by primary key.
+     * @param {string} table - Table name.
+     * @param {string} pk - Primary key column name.
+     * @param {*} pkVal - Primary key value.
+     * @param {object} data - Record data object.
+     */
+    async update(table, pk, pkVal, data)
+    {
+        const key = this._rowKey(table, pkVal);
+        const existing = this._deserialize(await this._client.get(key));
+        if (!existing) return;
+
+        for (const [k, v] of Object.entries(data))
+        {
+            existing[k] = v instanceof Date ? v.toISOString() : v;
+        }
+
+        await this._client.set(key, this._serialize(existing));
+    }
+
+    /**
+     * Update all rows matching conditions.
+     * @param {string} table - Table name.
+     * @param {object} conditions - Filter conditions.
+     * @param {object} data - Record data object.
+     * @returns {Promise<number>} Number of updated rows.
+     */
+    async updateWhere(table, conditions, data)
+    {
+        const rows = await this._getAllRows(table);
+        let count = 0;
+
+        const pipeline = this._client.pipeline();
+        for (const row of rows)
+        {
+            if (this._matchConditions(row, conditions))
+            {
+                for (const [k, v] of Object.entries(data))
+                {
+                    row[k] = v instanceof Date ? v.toISOString() : v;
+                }
+                pipeline.set(this._rowKey(table, row.id), this._serialize(row));
+                count++;
+            }
+        }
+        if (count > 0) await pipeline.exec();
+        return count;
+    }
+
+    /**
+     * Remove a row by primary key.
+     * @param {string} table - Table name.
+     * @param {string} pk - Primary key column name.
+     * @param {*} pkVal - Primary key value.
+     */
+    async remove(table, pk, pkVal)
+    {
+        const pipeline = this._client.pipeline();
+        pipeline.del(this._rowKey(table, pkVal));
+        pipeline.zrem(this._idsKey(table), String(pkVal));
+        await pipeline.exec();
+    }
+
+    /**
+     * Delete all rows matching conditions.
+     * @param {string} table - Table name.
+     * @param {object} conditions - Filter conditions.
+     * @returns {Promise<number>} Number of deleted rows.
+     */
+    async deleteWhere(table, conditions)
+    {
+        const rows = await this._getAllRows(table);
+        let count = 0;
+
+        const pipeline = this._client.pipeline();
+        for (const row of rows)
+        {
+            if (this._matchConditions(row, conditions))
+            {
+                pipeline.del(this._rowKey(table, row.id));
+                pipeline.zrem(this._idsKey(table), String(row.id));
+                count++;
+            }
+        }
+        if (count > 0) await pipeline.exec();
+        return count;
+    }
+
+    // -- Query Execution ----------------------------------
+
+    /**
+     * Execute a query descriptor (from the Query builder).
+     * @param {object} descriptor - Query descriptor object.
+     * @returns {Promise<Array|number>} Matching rows, or count if action is `'count'`.
+     */
+    async execute(descriptor)
+    {
+        const { action, table, fields, where, orderBy, limit, offset, distinct, groupBy, having } = descriptor;
+        let rows = await this._getAllRows(table);
+
+        // Apply WHERE filters
+        if (where && where.length > 0)
+        {
+            rows = rows.filter(row => this._applyWhereChain(row, where));
+        }
+
+        // Count action
+        if (action === 'count') return rows.length;
+
+        // GROUP BY
+        if (groupBy && groupBy.length > 0)
+        {
+            const groups = new Map();
+            for (const row of rows)
+            {
+                const key = groupBy.map(f => row[f]).join('\0');
+                if (!groups.has(key)) groups.set(key, { _key: {}, _rows: [] });
+                const g = groups.get(key);
+                for (const f of groupBy) g._key[f] = row[f];
+                g._rows.push(row);
+            }
+            rows = [];
+            for (const g of groups.values())
+            {
+                const row = { ...g._key };
+                row._groupRows = g._rows;
+                rows.push(row);
+            }
+
+            // HAVING
+            if (having && having.length > 0)
+            {
+                rows = rows.filter(row =>
+                {
+                    for (const h of having)
+                    {
+                        let actual;
+                        if (h.field === 'COUNT(*)' || h.field.startsWith('COUNT'))
+                        {
+                            actual = row._groupRows.length;
+                        }
+                        else
+                        {
+                            actual = row[h.field];
+                        }
+                        if (!this._compareOp(actual, h.op, h.value)) return false;
+                    }
+                    return true;
+                });
+            }
+
+            for (const row of rows) delete row._groupRows;
+        }
+
+        // ORDER BY
+        if (orderBy && orderBy.length > 0)
+        {
+            rows.sort((a, b) =>
+            {
+                for (const { field, dir } of orderBy)
+                {
+                    const av = a[field], bv = b[field];
+                    if (av < bv) return dir === 'ASC' ? -1 : 1;
+                    if (av > bv) return dir === 'ASC' ? 1 : -1;
+                }
+                return 0;
+            });
+        }
+
+        // OFFSET
+        if (offset) rows = rows.slice(offset);
+
+        // LIMIT
+        if (limit) rows = rows.slice(0, limit);
+
+        // SELECT specific fields
+        if (fields && fields.length > 0)
+        {
+            rows = rows.map(row =>
+            {
+                const filtered = {};
+                for (const f of fields) filtered[f] = row[f];
+                return filtered;
+            });
+        }
+
+        // DISTINCT
+        if (distinct)
+        {
+            const seen = new Set();
+            rows = rows.filter(row =>
+            {
+                const key = JSON.stringify(row);
+                if (seen.has(key)) return false;
+                seen.add(key);
+                return true;
+            });
+        }
+
+        return rows;
+    }
+
+    /**
+     * Compute an aggregate value.
+     * @param {object} descriptor - Query descriptor object.
+     * @returns {Promise<number|null>} Computed aggregate value.
+     */
+    async aggregate(descriptor)
+    {
+        const { table, where, aggregateFn, aggregateField } = descriptor;
+        let rows = await this._getAllRows(table);
+        if (where && where.length > 0)
+        {
+            rows = rows.filter(row => this._applyWhereChain(row, where));
+        }
+        const fn = aggregateFn.toLowerCase();
+        if (!rows.length) return (fn === 'count' || fn === 'avg' || fn === 'sum') ? 0 : null;
+        switch (fn)
+        {
+            case 'sum':   return rows.reduce((acc, r) => acc + (Number(r[aggregateField]) || 0), 0);
+            case 'avg':   return rows.reduce((acc, r) => acc + (Number(r[aggregateField]) || 0), 0) / rows.length;
+            case 'min':   return rows.reduce((m, r) => (r[aggregateField] < m ? r[aggregateField] : m), rows[0][aggregateField]);
+            case 'max':   return rows.reduce((m, r) => (r[aggregateField] > m ? r[aggregateField] : m), rows[0][aggregateField]);
+            case 'count': return rows.length;
+            default:      return null;
+        }
+    }
+
+    // -- Redis-Specific Operations ------------------------
+
+    /**
+     * Get a value by key (raw Redis GET).
+     * @param {string} key - Cache or storage key.
+     * @returns {Promise<string|null>} Stored value, or `null` if not found.
+     */
+    async get(key)
+    {
+        this._validateKey(key);
+        return this._client.get(this._prefix + key);
+    }
+
+    /**
+     * Set a key-value pair (raw Redis SET).
+     * @param {string} key - Cache or storage key.
+     * @param {*} value - Value to set.
+     * @param {number} [ttl] - Optional TTL in seconds.
+     * @returns {Promise<string>} Redis `"OK"` response.
+     */
+    async set(key, value, ttl)
+    {
+        this._validateKey(key);
+        if (ttl !== undefined && (!Number.isFinite(ttl) || ttl < 0))
+            throw new Error('Redis: TTL must be a non-negative number');
+        const k = this._prefix + key;
+        const v = typeof value === 'object' ? JSON.stringify(value) : String(value);
+        if (ttl) return this._client.setex(k, ttl, v);
+        return this._client.set(k, v);
+    }
+
+    /**
+     * Delete a key.
+     * @param {string} key - Cache or storage key.
+     * @returns {Promise<number>} Number of keys deleted (0 or 1).
+     */
+    async del(key)
+    {
+        this._validateKey(key);
+        return this._client.del(this._prefix + key);
+    }
+
+    /**
+     * Check if a key exists.
+     * @param {string} key - Cache or storage key.
+     * @returns {Promise<boolean>} `true` if the key exists.
+     */
+    async exists(key)
+    {
+        this._validateKey(key);
+        return (await this._client.exists(this._prefix + key)) === 1;
+    }
+
+    /**
+     * Set expiration on a key.
+     * @param {string} key - Cache or storage key.
+     * @param {number} seconds - Time in seconds.
+     * @returns {Promise<number>} `1` if timeout was set, `0` if key does not exist.
+     */
+    async expire(key, seconds)
+    {
+        this._validateKey(key);
+        if (!Number.isFinite(seconds) || seconds < 0)
+            throw new Error('Redis: TTL must be a non-negative number');
+        return this._client.expire(this._prefix + key, seconds);
+    }
+
+    /**
+     * Get TTL of a key in seconds.
+     * @param {string} key - Cache or storage key.
+     * @returns {Promise<number>} -1 if no expiry, -2 if key doesn't exist.
+     */
+    async ttl(key)
+    {
+        this._validateKey(key);
+        return this._client.ttl(this._prefix + key);
+    }
+
+    /**
+     * Increment a numeric key.
+     * @param {string} key - Cache or storage key.
+     * @param {number} [by=1] - Increment step.
+     * @returns {Promise<number>} Value after increment.
+     */
+    async incr(key, by = 1)
+    {
+        this._validateKey(key);
+        if (by === 1) return this._client.incr(this._prefix + key);
+        return this._client.incrby(this._prefix + key, by);
+    }
+
+    /**
+     * Decrement a numeric key.
+     * @param {string} key - Cache or storage key.
+     * @param {number} [by=1] - Increment step.
+     * @returns {Promise<number>} Value after decrement.
+     */
+    async decr(key, by = 1)
+    {
+        this._validateKey(key);
+        if (by === 1) return this._client.decr(this._prefix + key);
+        return this._client.decrby(this._prefix + key, by);
+    }
+
+    // -- Hash Operations ----------------------------------
+
+    /**
+     * Set a hash field.
+     * @param {string} key - Cache or storage key.
+     * @param {string} field - Field name.
+     * @param {*} value - Value to set.
+     * @returns {Promise<number>} `1` if field is new, `0` if updated.
+     */
+    async hset(key, field, value)
+    {
+        this._validateKey(key);
+        return this._client.hset(this._prefix + key, field, typeof value === 'object' ? JSON.stringify(value) : String(value));
+    }
+
+    /**
+     * Get a hash field.
+     * @param {string} key - Cache or storage key.
+     * @param {string} field - Field name.
+     * @returns {Promise<string|null>} Field value, or `null` if not found.
+     */
+    async hget(key, field)
+    {
+        this._validateKey(key);
+        return this._client.hget(this._prefix + key, field);
+    }
+
+    /**
+     * Get all fields in a hash.
+     * @param {string} key - Cache or storage key.
+     * @returns {Promise<object>} Object of field-value pairs.
+     */
+    async hgetall(key)
+    {
+        this._validateKey(key);
+        return this._client.hgetall(this._prefix + key);
+    }
+
+    /**
+     * Delete a hash field.
+     * @param {string} key - Cache or storage key.
+     * @param {string} field - Field name.
+     * @returns {Promise<number>} `1` if the field was removed, `0` if it did not exist.
+     */
+    async hdel(key, field)
+    {
+        this._validateKey(key);
+        return this._client.hdel(this._prefix + key, field);
+    }
+
+    // -- List Operations ----------------------------------
+
+    /**
+     * Push values to the end of a list.
+     * @param {string} key - Cache or storage key.
+     * @param {...*} values - Array of values.
+     * @returns {Promise<number>} Length of list after push.
+     */
+    async rpush(key, ...values)
+    {
+        this._validateKey(key);
+        return this._client.rpush(this._prefix + key, ...values.map(v => typeof v === 'object' ? JSON.stringify(v) : String(v)));
+    }
+
+    /**
+     * Push values to the beginning of a list.
+     * @param {string} key - Cache or storage key.
+     * @param {...*} values - Array of values.
+     * @returns {Promise<number>} Length of list after push.
+     */
+    async lpush(key, ...values)
+    {
+        this._validateKey(key);
+        return this._client.lpush(this._prefix + key, ...values.map(v => typeof v === 'object' ? JSON.stringify(v) : String(v)));
+    }
+
+    /**
+     * Get a range of list elements.
+     * @param {string} key - Cache or storage key.
+     * @param {number} [start=0] - Start offset.
+     * @param {number} [stop=-1] - Stop offset.
+     * @returns {Promise<string[]>} Array of list elements.
+     */
+    async lrange(key, start = 0, stop = -1)
+    {
+        this._validateKey(key);
+        return this._client.lrange(this._prefix + key, start, stop);
+    }
+
+    /**
+     * Pop from the end of a list.
+     * @param {string} key - Cache or storage key.
+     * @returns {Promise<string|null>} Removed element, or `null` if empty.
+     */
+    async rpop(key)
+    {
+        this._validateKey(key);
+        return this._client.rpop(this._prefix + key);
+    }
+
+    /**
+     * Pop from the beginning of a list.
+     * @param {string} key - Cache or storage key.
+     * @returns {Promise<string|null>} Removed element, or `null` if empty.
+     */
+    async lpop(key)
+    {
+        this._validateKey(key);
+        return this._client.lpop(this._prefix + key);
+    }
+
+    /**
+     * Get list length.
+     * @param {string} key - Cache or storage key.
+     * @returns {Promise<number>} Number of elements in the list.
+     */
+    async llen(key)
+    {
+        this._validateKey(key);
+        return this._client.llen(this._prefix + key);
+    }
+
+    // -- Set Operations -----------------------------------
+
+    /**
+     * Add members to a set.
+     * @param {string} key - Cache or storage key.
+     * @param {...*} members - Array of set members.
+     * @returns {Promise<number>} Number of members actually added.
+     */
+    async sadd(key, ...members)
+    {
+        this._validateKey(key);
+        return this._client.sadd(this._prefix + key, ...members.map(String));
+    }
+
+    /**
+     * Get all members of a set.
+     * @param {string} key - Cache or storage key.
+     * @returns {Promise<string[]>} Array of set members.
+     */
+    async smembers(key)
+    {
+        this._validateKey(key);
+        return this._client.smembers(this._prefix + key);
+    }
+
+    /**
+     * Check if a value is a member of a set.
+     * @param {string} key - Cache or storage key.
+     * @param {*} member - Set member.
+     * @returns {Promise<boolean>} `true` if the value is a member.
+     */
+    async sismember(key, member)
+    {
+        this._validateKey(key);
+        return (await this._client.sismember(this._prefix + key, String(member))) === 1;
+    }
+
+    /**
+     * Remove a member from a set.
+     * @param {string} key - Cache or storage key.
+     * @param {*} member - Set member.
+     * @returns {Promise<number>} `1` if the member was removed, `0` otherwise.
+     */
+    async srem(key, member)
+    {
+        this._validateKey(key);
+        return this._client.srem(this._prefix + key, String(member));
+    }
+
+    /**
+     * Get the number of members in a set.
+     * @param {string} key - Cache or storage key.
+     * @returns {Promise<number>} Number of members in the set.
+     */
+    async scard(key)
+    {
+        this._validateKey(key);
+        return this._client.scard(this._prefix + key);
+    }
+
+    // -- Sorted Set Operations ----------------------------
+
+    /**
+     * Add a member to a sorted set.
+     * @param {string} key - Cache or storage key.
+     * @param {number} score - Sort score.
+     * @param {*} member - Set member.
+     * @returns {Promise<number>} Number of members actually added.
+     */
+    async zadd(key, score, member)
+    {
+        this._validateKey(key);
+        return this._client.zadd(this._prefix + key, score, String(member));
+    }
+
+    /**
+     * Get members from a sorted set by score range.
+     * @param {string} key - Cache or storage key.
+     * @param {number|string} min - Minimum value.
+     * @param {number|string} max - Maximum value.
+     * @returns {Promise<string[]>} Array of matching members.
+     */
+    async zrangebyscore(key, min, max)
+    {
+        this._validateKey(key);
+        return this._client.zrangebyscore(this._prefix + key, min, max);
+    }
+
+    /**
+     * Get members from a sorted set by rank range.
+     * @param {string} key - Cache or storage key.
+     * @param {number} start - Start offset.
+     * @param {number} stop - Stop offset.
+     * @returns {Promise<string[]>} Array of members in rank order.
+     */
+    async zrange(key, start, stop)
+    {
+        this._validateKey(key);
+        return this._client.zrange(this._prefix + key, start, stop);
+    }
+
+    /**
+     * Remove a member from a sorted set.
+     * @param {string} key - Cache or storage key.
+     * @param {*} member - Set member.
+     * @returns {Promise<number>} Number of members removed.
+     */
+    async zrem(key, member)
+    {
+        this._validateKey(key);
+        return this._client.zrem(this._prefix + key, String(member));
+    }
+
+    /**
+     * Get sorted set cardinality.
+     * @param {string} key - Cache or storage key.
+     * @returns {Promise<number>} Number of members in the sorted set.
+     */
+    async zcard(key)
+    {
+        this._validateKey(key);
+        return this._client.zcard(this._prefix + key);
+    }
+
+    // -- Pub/Sub ------------------------------------------
+
+    /**
+     * Subscribe to a channel.
+     * @param {string} channel - Channel name.
+     * @param {Function} callback - Called with (message, channel).
+     * @returns {Promise<Function>} Unsubscribe function.
+     */
+    async subscribe(channel, callback)
+    {
+        this._validateKey(channel, 'channel');
+        if (typeof callback !== 'function')
+            throw new Error('Redis: subscribe callback must be a function');
+        if (!this._subClient)
+        {
+            this._subClient = this._client.duplicate();
+        }
+
+        const prefixedChannel = this._prefix + channel;
+        await this._subClient.subscribe(prefixedChannel);
+
+        const handler = (ch, message) =>
+        {
+            if (ch === prefixedChannel) callback(message, channel);
+        };
+        this._subClient.on('message', handler);
+
+        if (!this._subscribers.has(prefixedChannel))
+        {
+            this._subscribers.set(prefixedChannel, []);
+        }
+        this._subscribers.get(prefixedChannel).push({ callback, handler });
+
+        // Return unsubscribe function
+        return async () =>
+        {
+            this._subClient.removeListener('message', handler);
+            const subs = this._subscribers.get(prefixedChannel) || [];
+            const idx = subs.findIndex(s => s.callback === callback);
+            if (idx !== -1) subs.splice(idx, 1);
+            if (subs.length === 0)
+            {
+                await this._subClient.unsubscribe(prefixedChannel);
+                this._subscribers.delete(prefixedChannel);
+            }
+        };
+    }
+
+    /**
+     * Publish a message to a channel.
+     * @param {string} channel - Channel name.
+     * @param {*} message - Message payload.
+     * @returns {Promise<number>} Number of subscribers that received the message.
+     */
+    async publish(channel, message)
+    {
+        this._validateKey(channel, 'channel');
+        const msg = typeof message === 'object' ? JSON.stringify(message) : String(message);
+        return this._client.publish(this._prefix + channel, msg);
+    }
+
+    // -- Pipeline / Batch ---------------------------------
+
+    /**
+     * Create a pipeline for batching commands.
+     * @returns {Pipeline} Prefixed pipeline wrapper.
+     *
+     * @example
+     *   const pipe = adapter.pipeline();
+     *   pipe.set('key1', 'val1');
+     *   pipe.set('key2', 'val2');
+     *   const results = await pipe.exec();
+     */
+    pipeline()
+    {
+        const pipe = this._client.pipeline();
+        const adapter = this;
+
+        // Wrap to add prefix
+        return {
+            set(key, value, ...args)
+            {
+                pipe.set(adapter._prefix + key, typeof value === 'object' ? JSON.stringify(value) : String(value), ...args);
+                return this;
+            },
+            get(key) { pipe.get(adapter._prefix + key); return this; },
+            del(key) { pipe.del(adapter._prefix + key); return this; },
+            hset(key, field, value)
+            {
+                pipe.hset(adapter._prefix + key, field, typeof value === 'object' ? JSON.stringify(value) : String(value));
+                return this;
+            },
+            hget(key, field) { pipe.hget(adapter._prefix + key, field); return this; },
+            incr(key) { pipe.incr(adapter._prefix + key); return this; },
+            decr(key) { pipe.decr(adapter._prefix + key); return this; },
+            expire(key, seconds) { pipe.expire(adapter._prefix + key, seconds); return this; },
+            sadd(key, ...members) { pipe.sadd(adapter._prefix + key, ...members.map(String)); return this; },
+            rpush(key, ...values) { pipe.rpush(adapter._prefix + key, ...values.map(v => typeof v === 'object' ? JSON.stringify(v) : String(v))); return this; },
+            async exec() { return pipe.exec(); },
+        };
+    }
+
+    // -- Transaction Support ------------------------------
+
+    /**
+     * Begin a Redis MULTI transaction.
+     */
+    async beginTransaction()
+    {
+        this._multi = this._client.multi();
+    }
+
+    /**
+     * Commit a MULTI transaction.
+     */
+    async commit()
+    {
+        if (this._multi)
+        {
+            await this._multi.exec();
+            this._multi = null;
+        }
+    }
+
+    /**
+     * Discard a MULTI transaction.
+     */
+    async rollback()
+    {
+        if (this._multi)
+        {
+            this._multi.discard();
+            this._multi = null;
+        }
+    }
+
+    // -- Utility & Admin ----------------------------------
+
+    /**
+     * Clear all data (flush matched prefix keys).
+     * Uses SCAN for safety in production (no KEYS *).
+     */
+    async clear()
+    {
+        let cursor = '0';
+        do
+        {
+            const [nextCursor, keys] = await this._client.scan(cursor, 'MATCH', this._prefix + '*', 'COUNT', 100);
+            cursor = nextCursor;
+            if (keys.length > 0)
+            {
+                await this._client.del(...keys);
+            }
+        } while (cursor !== '0');
+    }
+
+    /**
+     * Ping the Redis server.
+     * @returns {Promise<boolean>} `true` if the server responds.
+     */
+    async ping()
+    {
+        try
+        {
+            const result = await this._client.ping();
+            return result === 'PONG';
+        }
+        catch (_)
+        {
+            return false;
+        }
+    }
+
+    /**
+     * Get Redis server info.
+     * @param {string} [section] - Optional section (e.g., 'memory', 'clients', 'stats').
+     * @returns {Promise<string>} Raw Redis INFO output.
+     */
+    async info(section)
+    {
+        return section ? this._client.info(section) : this._client.info();
+    }
+
+    /**
+     * Get database size (number of keys).
+     * @returns {Promise<number>} Total number of keys in the database.
+     */
+    async dbsize()
+    {
+        return this._client.dbsize();
+    }
+
+    /**
+     * List all table names (by scanning for schema keys).
+     * @returns {Promise<string[]>} Array of table names.
+     */
+    async tables()
+    {
+        const tables = [];
+        let cursor = '0';
+        const pattern = this._prefix + '*:_schema';
+        do
+        {
+            const [nextCursor, keys] = await this._client.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+            cursor = nextCursor;
+            for (const key of keys)
+            {
+                // Extract table name: zh:users:_schema → users
+                const stripped = key.slice(this._prefix.length);
+                const table = stripped.replace(/:_schema$/, '');
+                tables.push(table);
+            }
+        } while (cursor !== '0');
+        return tables;
+    }
+
+    /**
+     * Get stats for the adapter.
+     * @returns {Promise<object>} Adapter statistics.
+     */
+    async stats()
+    {
+        const tableNames = await this.tables();
+        let totalRows = 0;
+        for (const t of tableNames)
+        {
+            totalRows += await this._client.zcard(this._idsKey(t));
+        }
+        return {
+            tables: tableNames.length,
+            totalRows,
+            dbsize: await this._client.dbsize(),
+            prefix: this._prefix,
+        };
+    }
+
+    /**
+     * Get pool/connection status.
+     * @returns {{ status: string, prefix: string }}
+     */
+    poolStatus()
+    {
+        return {
+            status: this._client.status,
+            prefix: this._prefix,
+        };
+    }
+
+    /**
+     * Get the underlying ioredis client.
+     * @returns {object} The ioredis client instance.
+     */
+    get client()
+    {
+        return this._client;
+    }
+
+    /**
+     * Execute a raw Redis command.
+     * @param {string} command - Command name.
+     * @param {...*} args - Command arguments.
+     * @returns {Promise<*>} Command result.
+     */
+    async raw(command, ...args)
+    {
+        if (typeof command !== 'string' || command.length === 0)
+            throw new Error('Redis: command must be a non-empty string');
+        return this._client.call(command, ...args);
+    }
+
+    /**
+     * Close the connection.
+     */
+    async close()
+    {
+        if (this._subClient)
+        {
+            await this._subClient.quit();
+            this._subClient = null;
+        }
+        await this._client.quit();
+    }
+
+    // -- Migration / DDL Methods --------------------------
+
+    /**
+     * Add a column to an existing table.
+     * @param {string} table - Table name.
+     * @param {string} column - Column name.
+     * @param {object} def - Column definition.
+     */
+    async addColumn(table, column, def)
+    {
+        const schema = this._schemas.get(table);
+        if (schema) schema[column] = def;
+
+        const defaultVal = def.default !== undefined
+            ? (typeof def.default === 'function' ? def.default() : def.default)
+            : null;
+
+        // Update all existing rows
+        const rows = await this._getAllRows(table);
+        const pipeline = this._client.pipeline();
+        for (const row of rows)
+        {
+            if (row[column] === undefined)
+            {
+                row[column] = defaultVal;
+                pipeline.set(this._rowKey(table, row.id), this._serialize(row));
+            }
+        }
+        if (rows.length > 0) await pipeline.exec();
+
+        // Update stored schema
+        await this._client.set(this._schemaKey(table), JSON.stringify(this._schemas.get(table) || {}));
+    }
+
+    /**
+     * Drop a column from a table.
+     * @param {string} table - Table name.
+     * @param {string} column - Column name.
+     */
+    async dropColumn(table, column)
+    {
+        const schema = this._schemas.get(table);
+        if (schema) delete schema[column];
+
+        const rows = await this._getAllRows(table);
+        const pipeline = this._client.pipeline();
+        for (const row of rows)
+        {
+            delete row[column];
+            pipeline.set(this._rowKey(table, row.id), this._serialize(row));
+        }
+        if (rows.length > 0) await pipeline.exec();
+    }
+
+    /**
+     * Rename a column.
+     * @param {string} table - Table name.
+     * @param {string} oldName - Current name.
+     * @param {string} newName - New name.
+     */
+    async renameColumn(table, oldName, newName)
+    {
+        const schema = this._schemas.get(table);
+        if (schema && schema[oldName])
+        {
+            schema[newName] = schema[oldName];
+            delete schema[oldName];
+        }
+
+        const rows = await this._getAllRows(table);
+        const pipeline = this._client.pipeline();
+        for (const row of rows)
+        {
+            if (oldName in row)
+            {
+                row[newName] = row[oldName];
+                delete row[oldName];
+                pipeline.set(this._rowKey(table, row.id), this._serialize(row));
+            }
+        }
+        if (rows.length > 0) await pipeline.exec();
+    }
+
+    /**
+     * Rename a table.
+     * @param {string} oldName - Current name.
+     * @param {string} newName - New name.
+     */
+    async renameTable(oldName, newName)
+    {
+        const rows = await this._getAllRows(oldName);
+
+        // Create new table with all rows
+        const schema = this._schemas.get(oldName);
+        if (schema)
+        {
+            this._schemas.set(newName, schema);
+            this._schemas.delete(oldName);
+        }
+
+        const pipeline = this._client.pipeline();
+
+        // Copy sequence
+        const seq = await this._client.get(this._seqKey(oldName));
+        pipeline.set(this._seqKey(newName), seq || '0');
+
+        // Copy rows to new keys
+        for (const row of rows)
+        {
+            pipeline.set(this._rowKey(newName, row.id), this._serialize(row));
+            pipeline.zadd(this._idsKey(newName), Number(row.id) || 0, String(row.id));
+        }
+
+        // Store new schema
+        if (schema)
+        {
+            pipeline.set(this._schemaKey(newName), JSON.stringify(schema));
+        }
+
+        await pipeline.exec();
+
+        // Drop old table
+        await this.dropTable(oldName);
+    }
+
+    /**
+     * Create an index (tracked in metadata).
+     * @param {string} table - Table name.
+     * @param {string|string[]} columns - Column name(s).
+     * @param {{ name?: string, unique?: boolean }} [options={}]
+     */
+    async createIndex(table, columns, options = {})
+    {
+        const cols = Array.isArray(columns) ? columns : [columns];
+        const name = options.name || `idx_${table}_${cols.join('_')}`;
+        if (!this._indexes.has(table)) this._indexes.set(table, []);
+        this._indexes.get(table).push({ name, columns: cols, unique: !!options.unique });
+    }
+
+    /**
+     * Drop an index.
+     * @param {string} _table - Table name (unused).
+     * @param {string} name - Name identifier.
+     */
+    async dropIndex(_table, name)
+    {
+        for (const [, indexes] of this._indexes)
+        {
+            const idx = indexes.findIndex(i => i.name === name);
+            if (idx !== -1) { indexes.splice(idx, 1); return; }
+        }
+    }
+
+    /**
+     * Check if a table exists.
+     * @param {string} table - Table name.
+     * @returns {Promise<boolean>} `true` if the table exists.
+     */
+    async hasTable(table)
+    {
+        return (await this._client.exists(this._seqKey(table))) === 1 ||
+               (await this._client.exists(this._schemaKey(table))) === 1;
+    }
+
+    /**
+     * Check if a column exists on a table.
+     * @param {string} table - Table name.
+     * @param {string} column - Column name.
+     * @returns {Promise<boolean>} `true` if the column exists.
+     */
+    async hasColumn(table, column)
+    {
+        const schema = this._schemas.get(table);
+        if (schema) return column in schema;
+        // Check first row
+        const ids = await this._client.zrange(this._idsKey(table), 0, 0);
+        if (ids.length === 0) return false;
+        const row = this._deserialize(await this._client.get(this._rowKey(table, ids[0])));
+        return row ? column in row : false;
+    }
+
+    /**
+     * Describe a table's columns.
+     * @param {string} table - Table name.
+     * @returns {Promise<Array>} Array of column definitions.
+     */
+    async describeTable(table)
+    {
+        const schema = this._schemas.get(table);
+        if (!schema) return [];
+        return Object.entries(schema).map(([name, def]) => ({
+            name,
+            type: def.type || 'TEXT',
+            nullable: !def.required,
+            defaultValue: def.default !== undefined ? def.default : null,
+            primaryKey: !!def.primaryKey,
+        }));
+    }
+
+    /**
+     * Get indexes for a table.
+     * @param {string} table - Table name.
+     * @returns {Promise<Array>} Array of index definitions.
+     */
+    async indexes(table)
+    {
+        return this._indexes.get(table) || [];
+    }
+
+    // -- Internal Helpers ---------------------------------
+
+    /**
+     * Get all rows for a table.
+     * @private
+     * @param {string} table - Table name.
+     * @returns {Promise<object[]>} All rows in the table.
+     */
+    async _getAllRows(table)
+    {
+        const ids = await this._client.zrange(this._idsKey(table), 0, -1);
+        if (ids.length === 0) return [];
+
+        const pipeline = this._client.pipeline();
+        for (const id of ids)
+        {
+            pipeline.get(this._rowKey(table, id));
+        }
+        const results = await pipeline.exec();
+        const rows = [];
+        for (const [err, val] of results)
+        {
+            if (!err && val)
+            {
+                const row = this._deserialize(val);
+                if (row) rows.push(row);
+            }
+        }
+        return rows;
+    }
+
+    /** @private Match simple conditions. */
+    _matchConditions(row, conditions)
+    {
+        if (!conditions || typeof conditions !== 'object') return true;
+        for (const [k, v] of Object.entries(conditions))
+        {
+            if (row[k] !== v) return false;
+        }
+        return true;
+    }
+
+    /** @private Apply the where chain from query builder. */
+    _applyWhereChain(row, where)
+    {
+        let result = true;
+        for (let i = 0; i < where.length; i++)
+        {
+            const clause = where[i];
+            if (clause.raw) continue;
+            const matches = this._matchClause(row, clause);
+
+            if (i === 0 || clause.logic === 'AND')
+            {
+                result = i === 0 ? matches : (result && matches);
+            }
+            else if (clause.logic === 'OR')
+            {
+                result = result || matches;
+            }
+        }
+        return result;
+    }
+
+    /** @private Match a single WHERE clause. */
+    _matchClause(row, clause)
+    {
+        const val = row[clause.field];
+        const { op, value } = clause;
+
+        switch (op)
+        {
+            case '=':           return val === value;
+            case '!=':
+            case '<>':          return val !== value;
+            case '>':           return val > value;
+            case '<':           return val < value;
+            case '>=':          return val >= value;
+            case '<=':          return val <= value;
+            case 'LIKE':        return _likeSafe(String(val), String(value));
+            case 'IN':          return Array.isArray(value) && value.includes(val);
+            case 'NOT IN':      return Array.isArray(value) && !value.includes(val);
+            case 'BETWEEN':     return Array.isArray(value) && val >= value[0] && val <= value[1];
+            case 'NOT BETWEEN': return Array.isArray(value) && (val < value[0] || val > value[1]);
+            case 'IS NULL':     return val === null || val === undefined;
+            case 'IS NOT NULL':  return val !== null && val !== undefined;
+            default:            return val === value;
+        }
+    }
+
+    /** @private Compare for HAVING. */
+    _compareOp(actual, op, value)
+    {
+        switch (op.toUpperCase())
+        {
+            case '=':  return actual === value;
+            case '!=':
+            case '<>': return actual !== value;
+            case '>':  return actual > value;
+            case '<':  return actual < value;
+            case '>=': return actual >= value;
+            case '<=': return actual <= value;
+            default:   return actual === value;
+        }
+    }
+
+    /** @private Enforce unique constraints. */
+    async _enforceUnique(table, row, excludeRow)
+    {
+        const schema = this._schemas.get(table);
+        if (!schema) return;
+
+        const rows = await this._getAllRows(table);
+
+        for (const [col, def] of Object.entries(schema))
+        {
+            if (def.unique && row[col] !== undefined && row[col] !== null)
+            {
+                const duplicate = rows.find(r =>
+                    r !== excludeRow && r.id !== (excludeRow && excludeRow.id) && r[col] === row[col]
+                );
+                if (duplicate)
+                {
+                    throw new Error(`UNIQUE constraint failed: ${table}.${col}`);
+                }
+            }
+        }
+
+        // Composite unique
+        const groups = {};
+        for (const [col, def] of Object.entries(schema))
+        {
+            if (def.compositeUnique)
+            {
+                const g = typeof def.compositeUnique === 'string' ? def.compositeUnique : 'default';
+                if (!groups[g]) groups[g] = [];
+                groups[g].push(col);
+            }
+        }
+        for (const cols of Object.values(groups))
+        {
+            const duplicate = rows.find(r =>
+                r !== excludeRow && r.id !== (excludeRow && excludeRow.id) && cols.every(c => r[c] === row[c])
+            );
+            if (duplicate)
+            {
+                throw new Error(`UNIQUE constraint failed: ${table}.(${cols.join(', ')})`);
+            }
+        }
+    }
+}
+
+module.exports = RedisAdapter;