RDS workloads on kevy

You run an operational workload on MySQL or PostgreSQL and are considering moving it — wholly or partially — onto kevy. This page is the reference matrix: every SQL-surface construct, what carries it in kevy, the exact verbs, and the semantic deltas. Where kevy refuses a construct, the refusal is stated plainly along with the covered alternative. The companion cookbook turns these rows into runnable recipes; designing-on-kevy is the one-page map of the engine itself.

The division of labor

An RDS lets you write data first and decide the access paths later — the query planner turns any WHERE clause into some plan at query time. kevy inverts that: you declare the access paths at write time (indexes, aggregates, views), the engine maintains them synchronously with every write (derived-by-construction, zero drift), and serving is a microsecond-scale lookup, never a plan search. The trade is explicit:

• What you give up: ad-hoc queries over undeclared paths. A WHERE with no matching index is not slow on kevy — it is absent by design (model the access path or don't ship the query).
• What you get: predictable serving latency (hydrated page p99 < 1ms, write fan-out through index+view hooks p99 < 200µs on one server carrying the full stack — the gated lines in designing-on-kevy), and write absorption an RDS cannot match at the same durability setting (see Sizing).

Measured against PostgreSQL 18

Not asserted — run. 2M rows / 854 MB of CSV, one harness driving both, PG stock, median of three interleaved passes on kevy 5.4:

These numbers replace a set that was not comparing like with like. Until 5.4 the kevy read shapes asked for no columns while the SQL they were timed against selected two or three, and the kevy table declared six of the seven columns its rows carried. Both are fixed, and both moved the answer: the index lookup was published as 212 µs against PostgreSQL's 126 and is now a tie within 4%.

Read the rows as separate findings, because they point different ways. kevy absorbs writes 41× faster if one second of loss is acceptable — that is the pressure that puts a cache in front of an RDS in the first place. At matched per-write durability PostgreSQL is 2.0× faster: it group-commits its WAL, kevy fsyncs per command. On the indexed lookup the two engines are level; on the list page PostgreSQL is 1.2× faster — a planner over a B-tree is good at its job. And kevy holds the same data in 6.6× the memory: rows held in-process cost RAM. When the dataset stops fitting — 11.5 GB of CSV, PostgreSQL capped at 2 GB of memory, kevy at a 1 GB tiering budget — only the random-access shape changes hands: a lookup by random primary key is 184 µs on PG against 78 µs on tiered kevy, whose rows are on disk and still answer faster than a buffer-pool miss. The indexed shapes above stay with PG, and a follow-up run with predicates that genuinely scatter across the table widened rather than closed that gap — 176 µs against 385 µs on the indexed lookup. It is not an I/O effect: kevy loses it while holding everything in RAM, so the cost is the query path, not the fetch. Tiering holds the same 12 GB in 2.95 GB of RSS instead of 17.95 GB, and answers that lookup from the index without touching the 98 % of rows that live on disk.

The boundary is a charter, not a backlog: no query language, no planner, no joins, no server-side validation DSL, no triggers ("Law 3", designing-on-kevy). Everything below maps SQL constructs onto that fixed surface.

Tables, rows, columns

HSET user:42 name ada email ada@example.com age 36
HGETALL user:42                # SELECT * WHERE id = 42
HGET user:42 email             # SELECT email WHERE id = 42
HMGET user:42 name age         # SELECT name, age WHERE id = 42

HGET of a missing field answers nil — that IS the NULL semantics, and index specs treat a missing field as "row excluded" (counted, visible in IDX.VERIFY).

Type system

kevy stores bytes; types are declared where they matter — at index creation (TYPE i64|f64|str|vector). A row whose field fails the declared coercion is excluded from that index and counted (coerce_failures in IDX.VERIFY / IDX.LIST) — a declarative fence, never a write error.

PRIMARY KEY, UNIQUE, AUTO_INCREMENT

Primary key — the key itself. Point lookups (WHERE pk = ?) are GET/HGETALL/HMGET: one shard, one hash probe, no index needed.

AUTO_INCREMENT / sequences — INCR seq:order mints one id; INCRBY seq:order 100 allocates a block to hand out from app memory (the high-throughput form). Gaps on crash are the same contract PostgreSQL sequences give you (cookbook recipe 3).

UNIQUE — KIND unique is a fence, not a lock: it does not block writes (blocking would serialize cross-shard writes); duplicates are counted (duplicates in IDX.VERIFY) and visible as multi-hit EQ reads. For a hard uniqueness gate use one of:

SET uniq:email:ada@example.com 42 NX          # atomic claim, NX = the gate
WATCH + MULTI/EXEC check-then-write           # CAS loop (cookbook recipe 4)
{hashtag} prefix + single-shard domain        # cluster mode

SELECT

Semantics and limits, honestly:

• One field per index. An index covers one declared field of one prefix. Multi-column predicates are COMPOSE AND|OR of exactly two indexes (key-ordered — the two value domains differ, so key order is the only shared order), or a view for a named, reusable composition of up to 4 leaves. Wider ad-hoc conjunctions are the query-planner slope — refused. Filter residual predicates app-side after hydration.
• RANGE/EQ/COMPOSE: default LIMIT 100, max 10000, cursor pagination ([next-cursor, rows], "0" = start/exhausted). Cursor contract is SCAN-class: rows stable across the traversal are seen exactly once; concurrent writes may or may not appear. No global snapshot — same envelope as SCAN/DBSIZE.
• Prefix LIKE: a TYPE str KIND range index is ordered by lexicographic byte order, so LIKE 'abc%' is RANGE 'abc' 'abc<0xff>' — an index scan, not a keyspace walk. (Key-name prefix matching via SCAN 0 MATCH 'user:*' also exists but walks the whole keyspace incrementally — use it for ops chores, never as a serving path.)
• MATCH is OR-semantics over query tokens, BM25-ranked, CJK bigrams built in; LIMIT caps at 1000, no cursor; no phrase queries, no boolean syntax, no highlighting (text-search).
• FIELDS hydrates named hash fields on each row's owning shard in the same call — the one-hop replacement for the "index scan + primary lookup" double hop. This is also the JOIN-shaped hydration primitive (below).
• IDX.EXPLAIN is diagnostic only. It reports kind, state, est_rows, and the plan line for the query you already wrote — there is no optimizer choosing among plans.

Scalar functions

SQL expressions in migrated queries lean on a scalar-function vocabulary, and kevy covers it in the SQL face, not the engine: kevy-cli sql eval (and the sql toolbox's constant folding) evaluate expressions client-side with PostgreSQL-canonical semantics, and the serving engine never sees an expression — the same division of labor as everywhere else on this page.

Covered today (names matched case-insensitively, PG's fold):

The claims discipline behind that table:

• Semantics are probe-transcribed from PostgreSQL's own regression corpus and gated in CI (funcgate): a covered function answering differently from PG is a hard failure — the gate's wrong-answer count must be zero. The corpus-coverage ratio is a ratchet (currently ≥ 82 % of subset-foldable probes) that only moves up.
• Anything outside the table is refused by name, never guessed. The same goes for shapes inside a covered function that would change cardinality — regexp_matches returning zero or several rows is refused rather than flattened into a wrong scalar.

ORDER BY / LIMIT / OFFSET

• A range index is the order: IDX.QUERY … RANGE returns rows ascending by indexed value. ORDER BY col ASC LIMIT n = declare a range index on col, query with LIMIT n.
• Descending order on the bare index surface: not an IDX.QUERY option. Either declare a view (VIEW.CREATE … ORDER BY idx DESC) or store a negated/complemented sort field at write time.
• ORDER BY a, b (composite): encode the composite into one indexed field at write time — a * 1_000_000 + b for bounded integers, zero-padded strings for lexicographic composites (cookbook recipe 8).
• OFFSET exists on the claused surface, and you should still paginate with the cursor. This page used to say it did not exist; that was wrong — IDX.QUERY … OFFSET n parses and runs (see docs/tables.md). What is true is the cost: it is a "skip N rows", linear in n, and — unlike every other axis here — it gets worse as you add shards, because each shard must fetch limit + offset (none of them can know which of its hits survive the global merge) and the origin materialises (limit + offset) × shards hits to return limit. Measured on 30 000 in-range rows returning LIMIT 20: OFFSET 1000 costs 1.53 ms on one shard and 6.90 ms on eight; OFFSET 10000 costs 11.5 ms and 20.1 ms. Paginate with the returned cursor (constant cost per page, position-stable under the SCAN-class contract). If your product needs "jump to page 47", precompute page anchors or rethink the UX. kevy does not hide this cost — but until now it did not state it either, which is worse than hiding it.

GROUP BY and aggregates

KIND agg maintains aggregates in the write path — the inversion of GROUP BY: an RDS scans rows at query time, kevy folds each write into its group as it lands, and reading a group is O(1).

IDX.CREATE ord_amt ON PREFIX ord: FIELD amount TYPE i64 KIND agg GROUPBY status
IDX.QUERY ord_amt GROUP paid                  → [count, sum, min, max, avg]
IDX.QUERY ord_amt GROUPS BY sum LIMIT 100     → ranked [group, count, sum, min, max]

• GROUP g = SELECT COUNT(*), SUM(v), MIN(v), MAX(v), AVG(v) WHERE group = g; GROUPS BY count|sum|min|max = the ranked GROUP BY … ORDER BY agg LIMIT n (LIMIT ≤ 1000).
• min/max stay exact under deletion (per-group value multiset); sums accumulate in f64 — mind the precision bound for money (use minor units sized so totals stay well under 2^53).
• No HAVING, no aggregate expressions, no GROUP BY over arbitrary predicates — filter the (bounded) GROUPS result in the app. One group-by field per index; declare several agg indexes for several groupings.

JOIN

kevy does not join. No verb joins two prefixes server-side, and none ever will (Law 3). The three replacements, in order of preference:

1. Denormalize at write time. The serving-model answer: if the page shows order.total next to user.name, write user_name into the order row when it's created. Storage is cheap; the write hook keeps any indexes on the copy fresh. Update fan-out on the parent (rare for display fields) is a CDC consumer.
2. Application-side hydration (the two-hop). Foreign key lives in the row; an index makes the reverse direction one hop: IDX.QUERY order_user EQ 42 FIELDS total status is SELECT total, status FROM orders WHERE user_id = 42 — the index finds the keys and hydrates fields in the same call (cookbook recipe 2). The forward direction is HMGET per parent — batch the ids and pipeline.
3. A view with VIA hydration. VIEW.QUERY v FIELDS name VIA user:{key.1} dereferences each member key to a target key via a template and reads fields there — a declared, reusable member→parent dereference (one internal fan-out, no client round trips). Dereference, not query: targets take no predicates.

What you lose vs SQL: arbitrary N-way joins, join-time filtering on the far table, planner-chosen join order. What you gain: no join ever shows up in a latency histogram.

VIEW

VIEW.* is a named AND/OR/DIFF composition over declared indexes with an ordering index — closer to a materialized view with an index than to a SQL view:

VIEW.CREATE live_adults QUERY '( AND user_live EQ 0 user_age RANGE 18 200 )'
    ORDER BY user_age MODE materialized TOPK 100
VIEW.QUERY live_adults LIMIT 10 [FIELDS name] [VIA …]

The killer app is the hot list: "top 100 ready jobs by priority" as a TOPK materialized view costs ~2% write tax and answers in microseconds, permanently fresh — the thing an RDS needs a covering index + a disciplined query + luck to approximate (views).

Transactions

kevy's transaction story is Redis's (Law 1), which maps to SQL like this:

Isolation, honestly: kevy has no MVCC and no isolation-level knob. Within one shard, every command (and every EVAL, MULTI batch, or embedded atomic block) is serialized — you get serializable behavior for anything that fits one shard / one script. Across shards there is no global snapshot: multi-key reads (MGET, IDX.QUERY merges) are per-shard-atomic, SCAN-class overall. There is no read that observes a torn single command, and no dirty read of an uncommitted MULTI batch; there IS no repeatable-read across two separate commands — use WATCH (CAS) or Lua (one unit) where that matters.

Durability of a "commit": see persistence — with appendfsync always an acknowledged write is on disk before the reply; the default everysec windows up to 1s (the Redis trade). Store::fsync_aof() (embedded) is the per-transaction synchronous_commit escape hatch.

Constraints and triggers

There is deliberately no server-side constraint or trigger DSL: Lua scripts are the only server-side logic, and they run as the write, not attached to it.

Secondary index DDL

• Online build: IDX.CREATE returns immediately and backfills in the background (~7s per million small rows; multi-KB text bodies ~85s/M). Queries answer -INDEXBUILDING until ready — poll IDX.LIST for state=ready (migration). Data availability never waits on an index build.
• Index content is derived state: never snapshotted or AOF-logged, rebuilt in the background after restart. The catalog (the declarations) persists in a data-dir sidecar.
• Up to 64 indexes; MAXMEM caps a build declaratively (-INDEXOVERBUDGET) instead of growing unbounded.
• Bulk-load rule: import first, declare indexes after — backfill at bulk speed beats paying the write hook per imported row (cookbook recipe 15).

Pagination and optimistic locking patterns

• Keyset/cursor pagination (the good kind of OFFSET): every paged surface (IDX.QUERY RANGE/EQ/COMPOSE, VIEW.QUERY, SCAN) returns [next-cursor, rows]; feed the cursor back until "0". Treat cursors as opaque and single-traversal.
• Version-column optimistic locking: keep a version field, WATCH the row, read, MULTI + HSET … version n+1 + EXEC; nil reply = lost the race, retry (cookbook recipe 4).

Backup and PITR

Scope note on PITR: the feed window is an in-memory backlog (feed_buffer_size, caps 1 GiB/shard) — take snapshots at least as often as the window turns over if you rely on exact-point recovery. Verification is first-class: PREFIX.DIGEST / kevy-cli diff prove two keyspaces equal, order- and topology-insensitively.

Replication and read scaling

Primary + N replicas, asynchronous by default — the read-replica shape. The differences from an RDS are all in the consistency ladder (availability), which prices each guarantee per call instead of per instance:

Failover: planned handover is the FAILOVER verb (quiesce → drain → promote — zero-loss); crash failover is the 3-node elect quorum (MTTR ≈ 5–8s, offset-best candidate wins so WAIT-acked writes survive). A rejoining ex-primary's un-replicated tail is discarded (the forked suffix was never acked by definition) — the same data-loss shape as losing un-shipped binlog in MySQL semi-sync, made explicit. Every degraded state is a named error (-READONLY, -STALE, -NOREPLICAS, -QUIESCED, -MISDIRECTED) that a routing client self-heals from (error-replies).

CDC

The feed is kevy's binlog-as-API — what Debezium extracts from an RDS, served natively (cdc):

Not provided, deliberately: global cross-shard order (per-key order is guaranteed within a shard stream), server-side consumer positions, consumer groups. Retention is the in-memory backlog; falling behind answers -FEEDRESYNC with the cursor to rebuild from.

What kevy will NOT do

The refusals, in one place. Each is a charter decision (designing-on-kevy, the project's scope log) — not a roadmap gap:

Where that second row stops. "Not decide" is about query time: no plan is chosen for you, because your query names its own path. It is not a refusal to ever add one. TABLE.DECLARE … AUTODECLARE n lets the engine turn a shape you keep being refused into a declared path — off unless you ask, capped at the n you write, only over columns you declared, addition-only, and marked auto in IDX.LIST (tables.md). An optimiser you cannot predict and a schema change you asked for are different things, and only the first one is refused here.

One entry that used to sit in that table and does not belong there: OFFSET. It was listed as refused; the engine has always provided it on the claused surface (docs/tables.md), so the table was describing an intention rather than the behaviour. What is true, measured on 30 000 rows in range returning LIMIT 20 (p50 of 30 calls):

It is linear in the offset, and it gets worse as you add shards — each shard must fetch limit + offset because none of them can know which of its hits survive the global merge, so the origin materialises (limit + offset) × shards hits to return limit. Every other axis in this engine gets faster with more cores; this one does not.

Use cursors. OFFSET is there, it is not refused, and a deep one is the O(N) skip the rest of this table exists to keep out of your latency.

Sizing and operational deltas

Everything is RAM-resident. The working set that an RDS pages from disk lives in memory here; disk is the durability log + snapshot, not the serving tier. Capacity planning in one line:

RAM ≈ rows × (avg key len + avg row bytes + per-key overhead) + Σ per-index formula + view members × entry size — then verify against MEMORY USAGE / IDX.LIST bytes on a loaded sample.

The per-subsystem formulas (each gated against measured RSS in CI): range index ≈ rows × (value_width + avg_key_len + 48); text and ANN formulas in text-search / vector-search (1M × 1024d vectors ≈ 4.1 GiB); agg ≈ groups-dominated (indexes); view members ≈ order_value_width + key_len + 48 (views). Set maxmemory + an eviction policy or accept -OOM refusals (writes are rejected at admission — existing data is never corrupted).

Serving headroom. The arena, re-measured 2026-07-19 on v4.0.0 (kevy vs valkey 9.1, fair-fight protocol, median-of-5, throughput read from each server's own command counter — bench/ARENA-2026-07-19.txt): GET 2.46×, SET 4.00×, INCR 2.86×, SADD 2.95×, HSET 2.17×, ZADD 1.78×, LPUSH 1.76× — 7/7 wins with the full replication/heartbeat pipeline landed. Some of these ratios are lower than the v3.18.0 figures they replace, because that run read redis-benchmark's own rate, which is quantized low under --threads; counting server-side raised every engine's number, the competitors' by more. Against a disk-first RDS on point reads the gap is larger still; the honest comparison there is "kevy replaces the cache tier AND the operational queries", not a per-query benchmark.

Operational deltas vs an RDS, in brief: single keyspace (no schemas/databases — prefixes are the namespace); TTLs are first-class (EXPIRE, per-field HEXPIRE — the cron-delete job disappears); FLUSHALL is one command away (perimeter-protect it); derived state (indexes, views, feeds) rebuilds after restart rather than loading (seconds per million rows — budget it into restart time); and the error surface is part of the contract — clients should match error prefixes, not parse messages (error-replies).

This page vs the cookbook

This page is the reference matrix — SQL construct in, kevy shape out, deltas stated. The cookbook is the recipe book — 20 runnable patterns (every command block CI-smoked), each tagged with the SQL construct it replaces and cross-linked back to the matrix rows above. Migrating for real? The phased playbook is in migration.