Key-value store (Redis-like)

GET, SET, INCR, EXPIRE, DEL, KEYS, MGET and the other Redis string commands, hashes, sets, sorted sets, lists (with BLPOP), SORT and WATCH / MULTI / EXEC over HTTP (POST /kv, one command or a pipeline) and as SQL functions (kv_get, kv_set, kv_incr); PUBLISH / SUBSCRIBE and keyspace events. Keys are kept in memory and in the table _kv.

• Category: HTTP API
• Keywords: key-value, key value, kv, redis, POST /kv, /kv, GET, SET, SET NX, SET XX, SET EX, SETNX, SETEX, PSETEX, GETSET, GETDEL, GETEX, MGET, MSET, MSETNX, INCR, INCRBY, DECR, DECRBY, INCRBYFLOAT, counter, rate limit, APPEND, STRLEN, GETRANGE, SUBSTR, SETRANGE, LCS, DEL, UNLINK, EXISTS, TYPE, EXPIRE, PEXPIRE, EXPIREAT, PEXPIREAT, PERSIST, TTL, PTTL, EXPIRETIME, PEXPIRETIME, expiry, KEYS, SCAN, RANDOMKEY, DBSIZE, RENAME, RENAMENX, COPY, FLUSHDB, FLUSHALL, PING, ECHO, TIME, COMMAND, INFO, PUBLISH, SPUBLISH, PUBSUB, PUBSUB NUMSUB, PUBSUB CHANNELS, SUBSCRIBE, PSUBSCRIBE, pub/sub, keyspace events, notify-keyspace-events, CONFIG SET, CONFIG GET, __keyspace@0__, __keyevent@0__, expired event, KDB_NOTIFY_KEYSPACE_EVENTS, pipeline, kv_get, kv_set, kv_incr, kv_del, kv_expire, kv_ttl, kv(), _kv, sync, session store, cache, OTP, one-time code, CONFIG, maxmemory, maxmemory-policy, allkeys-lru, volatile-ttl, noeviction, appendonly, MEMORY USAGE, MEMORY STATS, kv_memory, eviction, LRU, hash, HSET, HGET, HGETALL, HINCRBY, HDEL, set, SADD, SMEMBERS, SINTER, SUNION, SDIFF, sorted set, ZADD, ZRANGE, ZRANK, ZINCRBY, ZPOPMIN, leaderboard, list, LPUSH, RPUSH, LPOP, LRANGE, LMOVE, queue, BLPOP, BRPOP, BLMOVE, BZPOPMIN, blocking pop, SORT, WATCH, MULTI, EXEC, UNWATCH, DISCARD, optimistic lock, session, _kv_items
• See also: CREATE TABLE (row-ttl), CREATE TABLE (cache-table), Run SQL over HTTP (/exec, /exp), PostgreSQL protocol (port 8832), LISTEN and NOTIFY

Every database has a key-value store that answers Redis's commands with Redis 7's answers: GET, SET (with EX, NX, XX, GET, KEEPTTL), INCR, EXPIRE, TTL, DEL, KEYS, MGET, MSET and more, and hashes, sets, sorted sets and lists. Use it for counters, rate limits, login sessions, one-time codes, caches, leaderboards and job queues.

Why it is fast: the keys are kept in memory, so a command is a look-up, not a SQL statement with a plan and table locks. The changes of many clients go to the disk together: one commit and one disk sync confirm all the changes that arrived meanwhile.

POST /kv

Syntax:

POST /kv[?db=name][&sync=on|off]

The body is one command, or a list of commands (a pipeline: one round trip for all of them). Words are JSON strings; a number may be written as a number.

// one command
await fetch('/kv', { method: 'POST', body: JSON.stringify(['INCR', 'visits']) });   // -> [1]
// a pipeline
await fetch('/kv', { method: 'POST', body: JSON.stringify([
  ['SET', 'otp:1', '123456', 'EX', 120],
  ['GET', 'otp:1'],
  ['TTL', 'otp:1'],
]) });                                                                             // -> ["OK","123456",120]

Plain text works too, one command per line, as you would type it in redis-cli ("..." keeps spaces in a word):

await fetch('/kv', { method: 'POST', body: 'SET greeting "hello world"\nGET greeting' });  // -> ["OK","hello world"]

The answer is always a JSON array with one reply per command:

A command that fails does not stop the ones after it, as in a Redis pipeline. A body that is not a command list gets 400.

• Rights: a body that only reads needs role read on the database; a body with any command that changes keys needs role write.
• Database: ?db=name, as for /exec. Each database has its own keys.

When the answer comes: sync

• CONFIG SET appendfsync always makes every request wait for the disk (each waiting request holds one HTTP thread until its sync, so many writing clients need more HTTP threads: kdb serve --http-threads). It is saved as the _kv table's synchronous_commit = on (durability per table) and survives a restart. everysec or no goes back to the default.
• Before 2026-10-03 the default waited for the disk; send ?sync=on (or set appendfsync always) to keep that.

The commands

• Expiry: a key whose time has come is gone at once for every command and for SELECT. A SET without KEEPTTL removes the old expiry, as in Redis.
• Errors read as Redis's: ERR wrong number of arguments for 'get' command, ERR syntax error, ERR value is not an integer or out of range, ERR no such key.
• Not here (yet): streams (XADD ...), SELECT n (use ?db=), Lua scripts, CLIENT TRACKING, DUMP/RESTORE.

Publish and subscribe

Redis's PUBLISH sends a message to every client that listens on a channel. Here it is the same channel as NOTIFY: a PUBLISH reaches LISTEN on the PostgreSQL port and GET /listen streams, and a NOTIFY reaches a pattern subscriber.

To subscribe, open a stream that stays open: a request and its answer cannot carry later messages, so SUBSCRIBE in /kv answers an error that says where to go.

// client 1: listen
const es = new EventSource('/listen?channel=news&pattern=price.*');
es.onmessage = (e) => console.log(JSON.parse(e.data));
// client 2: publish
await fetch('/kv', { method: 'POST', body: JSON.stringify([['PUBLISH', 'news', 'hi']]) });         // -> [1]
// client 1 gets {"channel":"news","payload":"hi","pid":0}
await fetch('/kv', { method: 'POST', body: 'PUBLISH price.NABIL 512' });                          // -> [1]
// client 1 gets {"channel":"price.NABIL","payload":"512","pid":0,"pattern":"price.*"}

Example: Publish from SQL

SELECT kv('PUBLISH', 'news', 'market opens at 11') AS listeners,
       kv('PUBSUB', 'NUMSUB', 'news') AS numsub;

Result:

(1 row)

• At once: PUBLISH sends when it runs, as in Redis. NOTIFY waits for its transaction to commit. Neither is stored: a listener that connects later does not get earlier messages.
• Rights: PUBLISH needs role write on the database (it reaches other clients); PUBSUB and listening need read. Channels belong to one database (?db=).
• Limits: a channel of up to 4096 bytes, a message of up to 1 MB. A listener that does not read is cut off rather than losing messages quietly (limits).

Keyspace events

With keyspace events on, every key change is published too, on Redis's channels:

@0 is Redis's first database, so a Redis client's subscription works unchanged; the channels still belong to one KDB database.

Turn them on with Redis's letters, as a server admin:

await fetch('/kv', { method: 'POST', body: 'CONFIG SET notify-keyspace-events Ex' });   // expired keys, keyevent channel
const es = new EventSource('/listen?channel=__keyevent@0__:expired');                  // payload: the key that expired

Example: Read the setting

SELECT kv('CONFIG', 'GET', 'notify-keyspace-events');

Result:

(1 row)

Example: Only an admin over HTTP may change it (shows an error)

SELECT kv('CONFIG', 'SET', 'notify-keyspace-events', 'KEA');

Result:

Error: line 1, column 8: kv: NOPERM CONFIG SET notify-keyspace-events changes the whole server: it needs a server admin

• The setting is for the whole server, as in Redis, and is off by default. CONFIG SET lasts until a restart; set KDB_NOTIFY_KEYSPACE_EVENTS=Ex in the environment to have it from the start. CONFIG SET notify-keyspace-events "" turns it off.
• While nobody listens anywhere, a key change does not build any event: the setting costs nothing until it is used.
• FLUSHDB sends no event per key, as in Redis.

A memory cap: CONFIG SET maxmemory

The store can be a cache with a size limit, as Redis with maxmemory:

await fetch('/kv', { method: 'POST', body: JSON.stringify([
  ['CONFIG', 'SET', 'maxmemory', '64mb', 'maxmemory-policy', 'allkeys-lru'],
]) });                                                       // -> ["OK"]

• Over the cap, a command that adds data first evicts keys by the policy, at once: the cap holds after every command. allkeys-lru takes the keys used longest ago (the oldest of 16 random keys, as Redis does), volatile-ttl the key that expires soonest, the volatile- ones only keys with an expiry.
• With noeviction (or nothing left that the policy may take), such a command fails with Redis's error OOM command not allowed when used memory > 'maxmemory'. DEL, EXPIRE and FLUSHDB still work.
• A key counts its own bytes, its value's bytes and 64 bytes: MEMORY USAGE key answers that, SELECT kv_memory() the whole store, INFO shows used_memory, maxmemory and evicted_keys.
• The settings are kept with the table _kv (its options max_bytes, evict, durability, as a cache table has), so they survive a restart. CONFIG SET needs role write (notify-keyspace-events, a server setting, a server admin); CONFIG GET only read.

Example: A store of 1 MB that forgets the oldest keys

SELECT kv('CONFIG', 'SET', 'maxmemory', '1mb', 'maxmemory-policy', 'allkeys-lru');
SELECT kv_set('session:1', 'sita'), kv('MEMORY', 'USAGE', 'session:1'), kv_memory();
SELECT kv('CONFIG', 'GET', 'maxmemory*');
SELECT kv('CONFIG', 'SET', 'maxmemory', '0', 'maxmemory-policy', 'noeviction');

Result:

SELECT kv('CONFIG', 'SET', 'maxmemory', '1mb', 'maxmemory-policy', 'allkeys-lru')

(1 row)

SELECT kv_set('session:1', 'sita'), kv('MEMORY', 'USAGE', 'session:1'), kv_memory()

(1 row)

SELECT kv('CONFIG', 'GET', 'maxmemory*')

(1 row)

SELECT kv('CONFIG', 'SET', 'maxmemory', '0', 'maxmemory-policy', 'noeviction')

(1 row)

Hashes, sets, sorted sets and lists

A key can hold more than one text. The commands and answers are Redis 7's; COMMAND DOCS HSET shows the syntax of each one.

await fetch('/kv', { method: 'POST', body: JSON.stringify([
  ['HSET', 'user:1', 'name', 'a', 'age', '3'],
  ['HINCRBY', 'user:1', 'age', '2'],
  ['HGETALL', 'user:1'],
  ['ZADD', 'board', 10, 'a', 20, 'b'],
  ['ZRANGE', 'board', 0, -1, 'WITHSCORES'],
]) });                                   // -> [2, 5, {"name":"a","age":"5"}, 2, ["a","10","b","20"]]

Example: A hash and a leaderboard from SQL

SELECT kv('HSET', 'user:1', 'name', 'Sita', 'age', '30'), kv('HINCRBY', 'user:1', 'age', '1'), kv('HGETALL', 'user:1');
SELECT kv('ZADD', 'board', '10', 'ram', '25', 'sita'), kv('ZRANGE', 'board', '0', '-1', 'REV', 'WITHSCORES');

Result:

SELECT kv('HSET', 'user:1', 'name', 'Sita', 'age', '30'), kv('HINCRBY', 'user:1', 'age', '1'), kv('H

(1 row)

SELECT kv('ZADD', 'board', '10', 'ram', '25', 'sita'), kv('ZRANGE', 'board', '0', '-1', 'REV', 'WITH

(1 row)

• HGETALL answers a JSON object; scores are texts ("10", "1.5"), and WITHSCORES lists are flat: [member, score, ...].
• SMEMBERS, SINTER, SUNION and SDIFF answer the members sorted, so the answer is the same every time (Redis's order changes).
• A command on a key of another type answers WRONGTYPE Operation against a key holding the wrong kind of value; so does GET of a hash.
• A hash, set or list that becomes empty is deleted, as in Redis. EXPIRE, TTL, DEL, RENAME, COPY and TYPE work on every type.
• They count toward the memory cap like strings, and eviction may take a whole hash, set or list.

Waiting for a value: BLPOP

BLPOP key [key ...] timeout takes the first value of the first list that has one. When all are empty it waits until another client pushes, up to timeout seconds (0.5 works; 0 = no limit), then answers null. BRPOP, BLMOVE, BRPOPLPUSH, BLMPOP, BZPOPMIN, BZPOPMAX and BZMPOP wait the same way.

// a worker: waits up to 5 s for a job
const [job] = await (await fetch('/kv', { method: 'POST', body: JSON.stringify(['BLPOP', 'jobs', 5]) })).json();
// -> ["jobs", "job-17"] as soon as someone runs ['RPUSH', 'jobs', 'job-17'], or null after 5 s

• The wait holds one HTTP thread: many waiting workers need more threads (kdb serve --http-threads).
• From SQL (kv('BLPOP', ...)) a blocking pop never waits: it answers at once, so a statement cannot hang.

WATCH, MULTI and EXEC

MULTI queues the commands after it and EXEC runs them together: no other client's command comes in between. WATCH key ... before MULTI makes EXEC answer null (and run nothing) when another client changed one of those keys meanwhile, so you read again and retry: an optimistic lock.

A Redis connection keeps its WATCH from one command to the next. Over HTTP, give your requests a session name: POST /kv?session=name. Requests with the same name (from the same user) share their WATCH and MULTI; a session ends 10 minutes after its last request. Without session, they last for that one request.

// request 1: read the stock and watch it
POST /kv?session=order-7   [["WATCH","stock"],["GET","stock"]]            // -> ["OK","5"]
// request 2: write it only if nobody changed it since
POST /kv?session=order-7   [["MULTI"],["SET","stock","4"],["EXEC"]]       // -> ["OK","QUEUED",["OK"]], or [..., null] to retry

• A command refused while queued (unknown, wrong number of words, no right to write) makes EXEC answer EXECABORT and run nothing, as in Redis.
• UNWATCH forgets the watched keys; DISCARD drops the queue.

From SQL: kv_get, kv_set, kv_incr

Syntax:

kv_get(key)                     -- GET
kv_set(key, value [, seconds])  -- SET key value [EX seconds]
kv_incr(key [, n])              -- INCRBY key n (1 when left out)
kv_del(key)                     -- DEL
kv_expire(key, seconds)         -- EXPIRE
kv_ttl(key)                     -- TTL
kv(command, word, ...)          -- any command: kv('MGET', 'a', 'b')

The same store, from any SQL client and the PostgreSQL port. A list answer (MGET, KEYS, LRANGE) comes as JSON text, and HGETALL as a JSON object. A NULL word gives NULL and changes nothing.

Example: A counter and a code that expires

SELECT kv_incr('page:home');
SELECT kv_incr('page:home', 10);
SELECT kv_set('otp:42', '815204', 120), kv_get('otp:42'), kv_ttl('otp:42');
SELECT kv('MGET', 'page:home', 'otp:42', 'nothing');

Result:

SELECT kv_incr('page:home')

(1 row)

SELECT kv_incr('page:home', 10)

(1 row)

SELECT kv_set('otp:42', '815204', 120), kv_get('otp:42'), kv_ttl('otp:42')

(1 row)

SELECT kv('MGET', 'page:home', 'otp:42', 'nothing')

(1 row)

Example: A counter needs a number (shows an error)

SELECT kv_set('name', 'sita'), kv_incr('name');

Result:

Error: line 1, column 32: kv_incr: ERR value is not an integer or out of range

• Rights: kv_get, kv_ttl and reading commands need role read; the others need role write, and so does kv() when its command is not written out as text (as in kv(col, 'k')). A read-only transaction (BEGIN READ ONLY) refuses them.
• On disk: the client's statement returns once its changes are on disk. Inside an open BEGIN ... COMMIT (and with SET synchronous_commit = off) it does not wait; the change is written within milliseconds. A key change is not part of the transaction: a ROLLBACK does not take it back.

The table _kv

The keys live in the table _kv of the database, made at the first change:

• SELECT reads it like any table: SELECT k, v FROM _kv WHERE k LIKE 'session:%'. Expired keys are not in it.
• Only the store changes it: INSERT, UPDATE, DELETE, TRUNCATE, DROP and ALTER of _kv are refused (42501). Empty it with FLUSHDB. TRUNCATE ALL TABLES empties the store too.
• It is in the log and in backups like any table, and the keys are back after a restart: the store reads _kv into memory when the database opens.
• Memory: every key and value is held in memory while the database is open, as in Redis. Keep big documents in tables, or set a cap.

Hashes, sets, sorted sets and lists are in a second table, _kv_items, made when the first one is: one row with the key's type (t) and expiry, and one row per field, member or list item (f, v). So HSET of one field writes one row, however big the hash is.

SELECT k, t, f, v FROM _kv_items WHERE k = 'user:1';
-- user:1 | hash | NULL | NULL
-- user:1 | NULL | age  | 31
-- user:1 | NULL | name | Sita

Only the store changes _kv_items too.