Storage, indexes, and optional facets
Each database has one Durable Object supervisor and an account-scoped R2 prefix. The service Worker authenticates the caller, resolves its database, and admits the request.
Ordinary database calls
Your Worker sends queries and atomic operation batches over HTTP. Live results use a WebSocket with a short-lived, query-scoped lease. The SDK manages this transport and maintains the current result with the existing flat-change receiver; it ships no database engine to callers.
The supervisor runs the WASM database engine, resolves page faults, and commits changed pages to its durable overlay. R2 holds immutable published bases. New databases start with an empty published base and initialize tables in the overlay; existing engine-format bases can still be uploaded.
Reads carry the version they observed. Conditional HTTP writes validate that version; facet transactions can additionally validate their recorded read answers. Callbacks may replay. Several transactions can be in flight, while commits serialize.
Indexes and bounded work
Indexes are declared in the TypeScript schema and are created with the table. The service does not infer or automatically build them. Uncovered filtering or ordering can scan object storage and exhaust a request budget. A limit does not necessarily bound the work needed to filter or sort.
Use db.explain(query), r2db explain, or development mode for schema/index advice before loading production data. Advice is conservative for complex query shapes and is not a measured planner output.
Recovery semantics
A keyed HTTP write records its receipt atomically with its committed pages. A repeat returns that same commit version for 24 hours. A lost response is an uncertain outcome until that receipt is checked by retrying the same write identity.
Live query snapshots and deltas reconstruct current query state. Hibernation restoration happens before dispatch, and reconnecting clients replace their state from a new snapshot. This is not an event-history or acknowledgment service.
Optional application facets
A facet runs your bundled Workers-compatible code beside the database and receives env.db through native RPC. It has separate local storage, no engine/R2/account binding, and outbound networking is disabled. Facets share the supervisor's thread; placement adds no CPU parallelism.
A code update activates only after startup validation and preserves the database. Each revision gets separate facet-local storage. Public application identities, mediated egress, facet subscriptions/migrations, capacity/compaction operations, recovery tools, and complete storage/live-query metering remain preview work.