Key-Value

Code

Write it. Read it. Same engine.

SET CONFIG acme.risk_threshold = 'high';

SELECT * FROM users WHERE risk = $config.acme.risk_threshold;

Build it

End-to-end walkthrough.

Four steps from empty database to a real key-value workload — each step shows the exact code and explains what the engine is doing.

1. Step 1

   1. Engine config — SET CONFIG, read inline via $config

   SET CONFIG <path> = <value> is the engine-config surface. Values are addressable from any SQL statement via $config.<path> as typed substitutions. Operations team adjusts at runtime — application code does not refetch.

   -- Set runtime knobs for your app.
   SET CONFIG acme.pagination.pageSize = 100;
   SET CONFIG acme.search.maxResults  = 50;
   SET CONFIG feature.new_dashboard   = 'on';
   
   -- Reference inline from any SQL statement.
   SELECT id, name FROM users
   ORDER BY id LIMIT $config.acme.pagination.pageSize;
   
   -- $config.<path> is resolved as a typed Value at parse time —
   -- not a textual splice — so SQL injection through config writes
   -- is structurally impossible.

2. Step 2

   2. Vault secrets — same shape, sealed reads

   red.secret.* keys are auto-encrypted with the vault AES key. $secret.<path> resolves the typed Value when policy allows; everyone else sees ***. Provider keys for AUTO EMBED, OAuth, payments — none of them ever land in your repo.

   -- Write under the red.secret.* namespace.
   SET CONFIG red.secret.openai.api_key   = 'sk-...';
   SET CONFIG red.secret.stripe.api_key   = 'sk_live_...';
   
   -- Reference inline; the engine pulls the typed Value from vault.
   INSERT INTO notes (body) VALUES ($1)
     WITH AUTO EMBED (body) USING openai;
   -- The OpenAI provider reads $red.secret.openai.api_key internally —
   -- never appears in your application code, logs, or query plans.
   
   -- Sealed read protects the value from non-privileged principals.
   SELECT $secret.red.secret.stripe.api_key;
   -- → '***' unless the policy allows the principal to UNSEAL.

3. Step 3

   3. User KV collection — SQL-queryable (key, value) rows

   User KV is shaped as KV collections — (key, value) rows you query with full SQL. WITH TTL evicts on the engine sweep; ON CONFLICT gives you idempotent writes without a separate CAS verb. Same WAL, same backup, same SELECT surface as any other table.

   -- Create a KV collection with a TTL on every entry.
   CREATE TABLE sessions KV (
     key      TEXT PRIMARY KEY,
     value    JSONB NOT NULL,
     created_at TIMESTAMPTZ NOT NULL DEFAULT now()
   );
   
   -- It is a regular collection — the full SQL surface applies.
   INSERT INTO sessions DOCUMENT (key, value)
   VALUES ('abc-123', {"user_id": 42, "scope": "admin"})
   WITH TTL 3600000;
   
   SELECT value FROM sessions WHERE key = 'abc-123';
   
   -- ON CONFLICT DO NOTHING gives you idempotent inserts.
   INSERT INTO idempotency (key, value) VALUES ($1, '1')
   ON CONFLICT (key) DO NOTHING
   RETURNING key;
   -- 0 rows back means the key already existed (replay).

4. Step 4

   4. Combine — config-driven query against a KV collection

   Config + vault references are typed-Value substitutions, so they compose with the rest of the SQL surface — they're available everywhere a literal would be. Tune at runtime, rotate secrets without redeploys, never touch the values in application code.

   -- Page-size knob in engine config.
   SET CONFIG acme.pagination.pageSize = 25;
   
   -- Iterate a KV namespace using the config knob.
   SELECT key, value
   FROM sessions
   WHERE key LIKE 'org:42:%'
   ORDER BY created_at DESC
   LIMIT $config.acme.pagination.pageSize;
   
   -- Combine with $secret for ops that need a vault value.
   INSERT INTO webhook_events (id, payload, signature_check)
   VALUES ($1, $2, hmac_sha256($2, $secret.red.secret.stripe.webhook_secret));

Showcases

What key-value can do once you bring the rest of the engine in.

Cross-model correlation, algorithm flex, multi-model patterns — things that take a stack of services elsewhere.

-- 1. Set the config (admin panel, deploy script, runbook).
SET CONFIG acme.pagination.pageSize = 100;

-- 2. Use it directly in any query.
SELECT id, name, created_at
FROM users
WHERE org_id = $1
ORDER BY id DESC
LIMIT $config.acme.pagination.pageSize;

-- 3. Tune at runtime — no app deploy.
SET CONFIG acme.pagination.pageSize = 250;
-- Subsequent queries pick up the new value on next execution.

-- Same pattern for vault secrets used inside SQL functions.
INSERT INTO notes (body) VALUES ($1)
  WITH AUTO EMBED (body) USING openai;
-- The engine reads $red.secret.openai.api_key from vault internally;
-- it never appears in your application code or query string.

-- Plain config — readable, durable, audited via WAL.
SET CONFIG config.risk_threshold = 'high';
SET CONFIG feature.new_dashboard = 'on';

-- Sensitive — auto-encrypted with vault AES key.
SET CONFIG red.secret.stripe_api_key = 'sk_live_...';
SET CONFIG red.secret.openai_api_key = 'sk-...';

-- Sealed read — $secret.<path> returns '***' unless the caller is authorized.
SELECT $secret.red.secret.stripe_api_key;
-- → '***'

-- Authorised principal sees the plaintext.
SET ROLE secrets_admin;
SELECT $secret.red.secret.stripe_api_key;
-- → 'sk_live_...'

async function withDeployLock<T>(workerId: string, fn: () => Promise<T>) {
  const acquired = await db.query(
    `INSERT INTO deploy_locks (name, holder, acquired_at)
     VALUES ('deploy', $1, NOW())
     ON CONFLICT (name) DO NOTHING`,
    [workerId],
  )
  if (acquired.rowCount === 0) throw new Error('lock taken')
  try {
    return await fn()
  } finally {
    await db.query(
      "DELETE FROM deploy_locks WHERE name = 'deploy' AND holder = $1",
      [workerId],
    )
  }
}

Recipes

Common patterns, real driver code.

INSERT INTO rate_limits (ip, window_start, count)
VALUES ($1, date_trunc('minute', NOW()), 1)
ON CONFLICT (ip, window_start)
DO UPDATE SET count = rate_limits.count + 1
RETURNING count;
-- if count > 100, reject the request.

const inserted = await db.query(
  `INSERT INTO idempotency_keys (key, created_at)
   VALUES ($1, NOW())
   ON CONFLICT (key) DO NOTHING`,
  [`stripe.${event.id}`]
)
if (inserted.rowCount === 0) return new Response('replay', { status: 200 })
// fresh event — process it

// Today: poll the config key.
const { rows } = await db.query(
  "SELECT value FROM app_config WHERE key = 'feature.new_dashboard'"
)
featureFlags.set('new_dashboard', rows[0]?.value === 'on')

vs

How RedDB key-value compare.

Pairs with

Key-Value earns more next to these.

The data models key-value compose with — a click away.

• tiered TTL

  Cache →

  KV is durable; Cache is ephemeral with TTL eviction. Configs in KV, sessions in Cache.

• relational

  Tables →

  KV stores configs that drive table queries — feature flags toggle SELECT branches without code change.

• workflows

  Queues →

  Idempotency keys live in KV; the corresponding job lives in a queue. INSERT ... ON CONFLICT coordinates exactly-once semantics.

Explore

Every other data model on RedDB.

One engine, 9 first-class data models. Mix as needed.

• relational

  Tables →

  Postgres-wire SQL with indexes, joins, transactions.

• json

  Documents →

  Schemaless JSON when structure is partial — query by path.

• edges

  Graphs →

  Native edges and traversals — multi-hop without a side-car.

• semantic

  Vectors →

  Auto-embed on insert, similarity search, no vector DB to sync.

• tiered TTL

  Cache →

  Tiered blob cache built into the engine: L1 memory + L2 durable.

• metrics

  Time-series →

  Retention, downsampling, native window queries.

• workflows

  Queues →

  FIFO, priority, consumer groups — durable workflow primitives.

• sketches

  Probabilistic →

  HyperLogLog, Count-Min Sketch, Cuckoo Filter — bounded-memory analytics.