durable-objects

Create one Durable Object per logical coordination unit such as a chat room, game session, or user, and access it with getByName using that entity's ID. Avoid a single global object, which becomes a bottleneck, and use parent-child objects for hierarchical data.

PRAGMA user_version is not supported, so track versions in a _sql_schema_migrations table and apply incremental changes inside blockConcurrencyWhile in the constructor. Libraries like durable-utils provide a SQLSchemaMigrations helper for production use.

Use @cloudflare/vitest-pool-workers with defineWorkersConfig pointing at your wrangler config. Tests can call stubs directly, use SELF.fetch for HTTP integration, runInDurableObject for internal storage assertions, and runDurableObjectAlarm to trigger alarms immediately.

Use blockConcurrencyWhile only for one-time initialization such as migrations, since it blocks all concurrency and roughly caps throughput at 200 requests per second. Never hold it across external I/O like fetch, R2, or KV calls.

No, each Durable Object supports exactly one scheduled alarm, and calling setAlarm replaces the existing one. Coordinate all scheduled work through a single alarm handler that reschedules itself based on the next due task.

Stateless request handlers and simple high-volume key lookups do not need a Durable Object; plain Workers with KV or D1 fit better. Durable Objects are justified when you need per-entity coordination, strongly consistent state, or persistent WebSocket connections.