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 raw Redis-parity throughput far above what a B-tree-on-disk engine serves (see Sizing).

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.

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 does not exist. There is deliberately no "skip N rows" — it is O(N) waste in any engine and an anti-pattern at depth. 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 will not hide the cost.

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:

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 v3.18.0 release arena (kevy vs valkey 9.1, fair-fight protocol, median-of-5 — bench/PERF-LEDGER.md): GET 3.00×, SET 3.99×, INCR 3.00×, SADD 2.50×, HSET 2.25×, ZADD 1.73×, LPUSH 1.64× — 7/7 wins with the full replication/heartbeat pipeline landed. 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.