Skip to content
Storage / KV

Storage

KV

Run Workers KV namespaces on OpenOrange, where each namespace is one Rivet Actor with its own SQLite database.

Drop-in

Runs on Internal Rivet Actor per namespace

Works
get(), getWithMetadata(), put(), delete(), and list(), with metadata, expiration, and bulk reads
Differs
Reads are strongly consistent, and Cloudflare's KV quotas do not apply
Missing
The edge cache (cacheTtl and cacheStatus) and an orange kv command
Migration
Not supported orange migrate does not move KV namespaces. Copy the data yourself.
Configure
kv_namespaces
Scales by
Namespace
Checks
1 pass

A KV namespace on OpenOrange is one Rivet Actor with its own SQLite database. Your KV code and Wrangler configuration run unchanged.

Quickstart

  1. Bind the namespace

    Add a kv_namespaces entry to wrangler.jsonc. Keep your Cloudflare id: Orange uses it as the namespace’s name.

    {
      "name": "kv",
      "main": "src/index.ts",
      "compatibility_date": "2026-09-03",
      "kv_namespaces": [{ "binding": "NOTES", "id": "kv-example-notes" }]
    }
  2. Read and write keys

    Call the namespace from env, as on Cloudflare.

    interface Env {
      NOTES: KVNamespace;
    }
    
    export default {
      async fetch(request, env): Promise<Response> {
        const key = /^\/notes\/(.+)$/.exec(new URL(request.url).pathname)?.[1];
        if (key === undefined) return new Response("Try /notes/<key>", { status: 404 });
        switch (request.method) {
          case "PUT":
            await env.NOTES.put(key, await request.text());
            return new Response(null, { status: 204 });
          case "DELETE":
            await env.NOTES.delete(key);
            return new Response(null, { status: 204 });
          default: {
            const value = await env.NOTES.get(key);
            return value === null
              ? new Response(`No note named ${key}`, { status: 404 })
              : new Response(value);
          }
        }
      },
    } satisfies ExportedHandler<Env>;
  3. Run it

    orange dev shows the namespace as a Rivet Actor.

    orange dev
      Binding     Resource       Runs on
      env.NOTES   KV Namespace   Rivet Actor

    Write a note, read it back, and delete it:

    curl -X PUT localhost:8787/notes/todo-1 -d 'buy milk'
    curl localhost:8787/notes/todo-1
    buy milk
    curl -X DELETE localhost:8787/notes/todo-1
    curl localhost:8787/notes/todo-1
    No note named todo-1

How it works

  • Each namespace is one Rivet Actor with a SQLite database.
  • Under orange dev, it lives in your project’s .open-orange directory, so keys survive a restart. After orange deploy, it runs on your Rivet cluster.
  • One actor serves every call on its namespace. To spread load, use more than one namespace.
AI context Compatibility, limits and details

Written for LLMs and coding agents: every edge case, measurement, and known deviation. You do not need it to use the feature.

Compatibility

FeatureStatusNotes
get() and getWithMetadata(), with the text, json, arrayBuffer, and stream typesSupportedA stream read loads the whole value first.
Bulk get() and getWithMetadata() with an array of keysSupportedtext and json only, as on Cloudflare. No 100-key limit.
put() with a string, ArrayBuffer, ArrayBufferView, or ReadableStreamSupportedA stream is read whole before it is stored.
expiration and expirationTtlSupportedNo 60-second minimum.
metadataSupportedNo 1,024-byte limit.
delete()Supported
list() with prefix, limit, and cursorSupportedKeys list in UTF-8 byte order. A page holds 1,000 keys by default, and limit has no maximum.
cacheTtlPartialChecked, then ignored.
cacheStatusPartialAlways null.
wrangler kv commandsNot supportedorange kv prints that the command is not implemented.

Two differences reach most projects:

  • Reads are strongly consistent. A read anywhere sees the last write. On Cloudflare, a read in another location can return an older value for up to 60 seconds.
  • Cloudflare’s quotas do not apply, so a write that Cloudflare would refuse succeeds, such as a value over 25 MiB or a 30-second TTL. Rivet’s limit on one write applies instead. See Limits.

Limits

WhatLimitWhat happens over it
One put()Key, value, and metadata together under 128 MiB, Rivet’s limit for one writeThe put() throws a RangeError at once that names the limit. The namespace keeps working.
A large value64 MiB stored and read back in a test on Rivet 3.0.6A 100 MiB value made the Engine fence the namespace’s storage, and the put() did not return. That is a Rivet issue under one large write, not a set limit.
Calls on one namespaceWhat one Rivet Actor servesSpread the keys over more namespaces.

What Orange reads

On Orange, id only names the namespace, so a Cloudflare namespace ID works as it is.

In wrangler.jsoncOn Orange
idNames the namespace. Under orange dev, a preview_id wins, as in wrangler dev. With neither, the binding name names it. orange serve and a deployed Worker skip preview_id, as wrangler deploy does.
The same id on two bindingsOne namespace, also for every Worker of one orange dev session. See Multiple Workers.

API details

  • get() takes a type string or { type, cacheTtl }. The type defaults to text. Another type throws Unknown response type. Possible types are "text", "arrayBuffer", "json", and "stream".
  • A bulk get() returns a Map with null for a missing key. It needs at least one key, and a type other than text or json fails with KV GET_BULK failed: 400 "<type>" is not a valid type. Use "json" or "text". A bulk json read of a value that is not JSON fails with At least one of the requested keys corresponds to a non-json value.
  • cacheTtl must be greater than 0, or the call fails with Invalid cache_ttl of <n>. Please specify integer greater than 0.
  • put() turns other primitives into strings, as workerd does. An object that is not one of the accepted types throws KV put() accepts only strings, ArrayBuffers, ArrayBufferViews, and ReadableStreams as values. A stream must produce Uint8Array chunks.
  • expirationTtl must be an integer greater than 0. expiration must be later than the current second. Each fails with the KV PUT failed: 400 ... text of Miniflare.
  • An empty key, ., and .. are refused with workerd’s messages. A key has no 512-byte limit.
  • metadata is stored as JSON and parsed again on each read.
  • list() uses a limit of 1,000 when it is missing or not above 0. The cursor is the last returned key, base64url-encoded. Listed keys carry expiration and metadata when they have them, and expired keys are left out.
  • A failed call throws KV <METHOD> failed: <status> <message>.

Argument checks and error text follow workerd’s KV client and the local KV backend of wrangler dev.

Storage

  • The actor class is openorange:kv-namespace, shown as KV namespaces (Orange), and its key is the namespace ID.
  • Under orange dev, the namespace’s storage sits in .open-orange next to Durable Object storage.
  • Entries are rows of one table, openorange_kv, with the key, the value, the expiration, and the metadata.
  • A read of an expired key deletes its row.
  • Keys and metadata travel in the request body to the actor, so URL and header size limits do not bound them.
  • One actor is the single writer for its namespace, so every get(), put(), delete(), and list() on a namespace goes through it.

Deviations

These add to the two differences under Compatibility.

  • An expired key reads as absent at once, from its expiration second.
  • Cloudflare’s quotas that Orange does not copy: 512-byte keys, 1,024-byte metadata, 25 MiB values, 100 keys per bulk read, 1,000 keys per list() page, and TTLs of at least 60 seconds.
  • put() buffers the whole value before it stores it.
  • Cloudflare spreads reads across its edge and has no one-actor throughput bound. Sharding a namespace across actors, or backing KV with a Rivet Service, may lift that bound later.

Conformance

  • tests/bindings/bindings.test.ts drives KV through a real orange dev and Rivet Engine: every value and result type, metadata, bulk reads, listing with pagination, error text, shared and separate namespace IDs, overlapping writes, and persistence across restarts. The same Worker returns identical results under wrangler dev.
  • tests/bindings/beyond-cloudflare-quotas.test.ts writes keys, metadata, values, bulk reads, lists, and TTLs past Cloudflare’s quotas, and a write over 128 MiB that fails with Rivet’s limit.
  • tests/rpc-and-websockets/session-shared-storage.test.ts checks that the Workers of one session share a namespace by ID.
  • tests/examples/runnable-examples.test.ts runs the kv example, including a 30-second TTL that Cloudflare refuses.
  • workerd’s upstream kv-test passes 0 of 5. It needs a mock KV server that the conformance runner does not configure, and its deleteBulk case calls a method that the pinned Wrangler declarations do not have. kv-resizable-arraybuffer-test passes 3 of 3.
Recorded results

Recorded results from the conformance run of 2026-11-10 (Orange ea40348), 1,670 of 1,851 tests passing across every area. Each check is works when every result passed and partial when some did. The full feature matrix is on the compatibility page.

KV
Check Status Results
KV Works
  • Pass: example: kv