durable-objects

Extend the DurableObject class from cloudflare:workers and configure new_sqlite_classes in your wrangler migrations. Initialize tables inside the constructor using ctx.blockConcurrencyWhile, then run synchronous queries via this.ctx.storage.sql.exec.

Use @cloudflare/vitest-pool-workers with defineWorkersConfig pointing at your wrangler config. Access stubs via env from cloudflare:test, inspect internals with runInDurableObject, and trigger alarms instantly with runDurableObjectAlarm.

Use Durable Objects when you need coordination, strong consistency, per-entity storage, or persistent WebSocket connections, such as chat rooms or booking systems. Use plain Workers for stateless request handling or high fan-out independent requests.

blockConcurrencyWhile blocks all concurrency in the instance, so using it on every request caps throughput at roughly 200 requests per second. Reserve it for one-time constructor initialization and never hold it across fetch or external I/O.

No, PRAGMA user_version is not supported in Durable Objects SQLite storage. Track schema versions in a dedicated _sql_schema_migrations table and apply incremental migrations during constructor initialization.

Each Durable Object supports one alarm at a time, and calling setAlarm replaces any existing alarm. Implement an async alarm() handler to process scheduled work, optionally rescheduling by calling setAlarm again, and keep handlers idempotent since failed alarms auto-retry.