durable-objects

Extend the DurableObject class from cloudflare:workers and initialize tables inside the constructor using ctx.blockConcurrencyWhile with ctx.storage.sql.exec. Register the class in wrangler.jsonc migrations using new_sqlite_classes so the SQLite backend is enabled.

Use env.MY_DO.getByName("room-123") for deterministic routing so the same name always maps to the same instance. For existing IDs use idFromString with get(), and for new entities use newUniqueId() while storing the mapping externally.

SQLite storage is recommended for new classes and is configured via new_sqlite_classes in migrations. Existing KV-backed classes can keep the legacy KV API, but you should inspect the backend of existing classes before selecting storage APIs.

Use Cloudflare's Vitest integration to run Durable Objects in the Workers runtime, testing RPC methods, instance isolation, SQLite persistence, and alarms. The testing reference links to setup, migration guides, and helper APIs for triggering alarms without waiting for wall-clock time.

Avoid Durable Objects for stateless request handling, maximum global distribution, or high fan-out independent requests; plain Workers fit those cases better. Also never use a single global Durable Object for all requests, since it becomes a bottleneck.

blockConcurrencyWhile blocks all other requests until it completes, so using it on every request kills throughput. It should only wrap schema initialization in the constructor and must never span fetch() calls or external I/O.