Storage
KV
Run Workers KV namespaces on OpenOrange, where each namespace is one Rivet Actor with its own SQLite database.
Runs on Internal Rivet Actor per namespace
- Works
get(),getWithMetadata(),put(),delete(), andlist(), with metadata, expiration, and bulk reads- Differs
- Reads are strongly consistent, and Cloudflare's KV quotas do not apply
- Missing
- The edge cache (
cacheTtlandcacheStatus) and anorange kvcommand - Migration
- Not supported
orange migratedoes 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
-
Bind the namespace
Add a
kv_namespacesentry towrangler.jsonc. Keep your Cloudflareid: 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" }] } -
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>; -
Run it
orange devshows the namespace as a Rivet Actor.orange dev Binding Resource Runs on env.NOTES KV Namespace Rivet ActorWrite 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-orangedirectory, so keys survive a restart. Afterorange 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
| Feature | Status | Notes |
|---|---|---|
get() and getWithMetadata(), with the text, json, arrayBuffer, and stream types | Supported | A stream read loads the whole value first. |
Bulk get() and getWithMetadata() with an array of keys | Supported | text and json only, as on Cloudflare. No 100-key limit. |
put() with a string, ArrayBuffer, ArrayBufferView, or ReadableStream | Supported | A stream is read whole before it is stored. |
expiration and expirationTtl | Supported | No 60-second minimum. |
metadata | Supported | No 1,024-byte limit. |
delete() | Supported | |
list() with prefix, limit, and cursor | Supported | Keys list in UTF-8 byte order. A page holds 1,000 keys by default, and limit has no maximum. |
cacheTtl | Partial | Checked, then ignored. |
cacheStatus | Partial | Always null. |
wrangler kv commands | Not supported | orange 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
| What | Limit | What happens over it |
|---|---|---|
One put() | Key, value, and metadata together under 128 MiB, Rivet’s limit for one write | The put() throws a RangeError at once that names the limit. The namespace keeps working. |
| A large value | 64 MiB stored and read back in a test on Rivet 3.0.6 | A 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 namespace | What one Rivet Actor serves | Spread 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.jsonc | On Orange |
|---|---|
id | Names 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 bindings | One 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 totext. Another type throwsUnknown response type. Possible types are "text", "arrayBuffer", "json", and "stream".- A bulk
get()returns aMapwithnullfor a missing key. It needs at least one key, and a type other thantextorjsonfails withKV GET_BULK failed: 400 "<type>" is not a valid type. Use "json" or "text". A bulkjsonread of a value that is not JSON fails withAt least one of the requested keys corresponds to a non-json value. cacheTtlmust be greater than 0, or the call fails withInvalid 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 throwsKV put() accepts only strings, ArrayBuffers, ArrayBufferViews, and ReadableStreams as values.A stream must produceUint8Arraychunks.expirationTtlmust be an integer greater than 0.expirationmust be later than the current second. Each fails with theKV PUT failed: 400 ...text of Miniflare.- An empty key,
., and..are refused with workerd’s messages. A key has no 512-byte limit. metadatais stored as JSON and parsed again on each read.list()uses alimitof 1,000 when it is missing or not above 0. The cursor is the last returned key, base64url-encoded. Listed keys carryexpirationandmetadatawhen 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 asKV namespaces (Orange), and its key is the namespace ID. - Under
orange dev, the namespace’s storage sits in.open-orangenext 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(), andlist()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.tsdrives KV through a realorange devand 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 underwrangler dev.tests/bindings/beyond-cloudflare-quotas.test.tswrites 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.tschecks that the Workers of one session share a namespace by ID.tests/examples/runnable-examples.test.tsruns thekvexample, including a 30-second TTL that Cloudflare refuses.- workerd’s upstream
kv-testpasses 0 of 5. It needs a mock KV server that the conformance runner does not configure, and itsdeleteBulkcase calls a method that the pinned Wrangler declarations do not have.kv-resizable-arraybuffer-testpasses 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 |
|