WIP: [DO] Document delayed code updates

src/content/changelog/durable-objects/2026-08-13-durable-objects-deferred-code-updates.mdx

@@ -0,0 +1,47 @@
+---
+title: Defer code updates until active Durable Objects hibernate
+description: Set a code update strategy so active Durable Objects finish their current work before a code update replaces them.
+products:
+  - durable-objects
+  - workers
+date: 2026-08-13
+---
+
+import { WranglerConfig, PackageManagers } from "~/components";
+
+{/* TODO: Confirm the launch date and compatibility date before publication. */}
+
+Durable Objects can stay active across requests, allowing you to run long-running [agents](/agents/), maintain [long-lived WebSocket connections](/durable-objects/best-practices/websockets/) and coordinate state across many clients. This is possible because each Durable Object is globally unique, and this means it must run only one version of your code at a time. Previously, when you deployed a change to your Durable Objects code, that change would be applied immediately, which could interrupt in-flight work and terminate open connections.
+
+You can now set a Durable Object's code update strategy to `deferred`, which tells Cloudflare to wait for the Durable Object to hibernate before it applies the update. This lets in-flight work finish before code updates and keeps open WebSocket connections that use the [Hibernation API](/durable-objects/examples/websocket-hibernation-server/) connected.
+
+Add `code_update_strategy` to `durable_objects` in your Wrangler configuration:
+
+<WranglerConfig>
+
+```jsonc
+{
+	"durable_objects": {
+		"bindings": [
+			{
+				"name": "CHAT_ROOM",
+				"class_name": "ChatRoom",
+			},
+		],
+		"code_update_strategy": {
+			"mode": "deferred",
+			"max_delay": 60,
+		},
+	},
+}
+```
+
+</WranglerConfig>
+
+`max_delay` is in seconds, up to a maximum of `300` (five minutes). Omit it to use the default for your compatibility date. Set `mode` to `immediate` — or pass `--durable-objects-code-update-mode immediate` for a single deployment — to apply an update right away, for example during an incident:
+
+<PackageManagers type="exec" pkg="wrangler" args="versions deploy <VERSION_ID>@100% --durable-objects-code-update-mode immediate" />
+
+A `deferred` code update is best-effort, not a guarantee. Cloudflare can still reset an object before `max_delay` is reached.
+
+For more information, including how this interacts with gradual deployments and the REST API, refer to [Defer code updates until hibernation](/durable-objects/deployments/durable-objects-code-updates/).

src/content/docs/durable-objects/best-practices/access-durable-objects-storage.mdx

@@ -17,7 +17,13 @@ storage. Durable Objects
 <GlossaryTooltip term="Storage API">Storage API</GlossaryTooltip> provides
 access to a Durable Object's attached storage.
 
-A Durable Object's [in-memory state](/durable-objects/reference/in-memory-state/) is preserved as long as the Durable Object is not evicted from memory. Inactive Durable Objects with no incoming request traffic can be evicted. There are normal operations like [code deployments](/workers/versions-and-deployments/) that trigger Durable Objects to restart and lose their in-memory state. For these reasons, you should use Storage API to persist state durably on disk that needs to survive eviction or restart of Durable Objects.
+A Durable Object's [in-memory state](/durable-objects/reference/in-memory-state/) is preserved as long as the Durable Object remains in memory. Inactive Durable Objects with no incoming request traffic can be evicted.
+
+When you deploy a code change to Durable Objects, by default this change is immediately applied — Cloudflare creates a fresh isolate that runs the new version of your code, and any in-memory state is discarded.
+
+To give your application time to finish in-flight work or persist in-memory state to [SQLite](/durable-objects/api/sqlite-storage-api/) or to external storage, you can set a Durable Object's [code update strategy](/durable-objects/deployments/durable-objects-code-updates/) to `deferred`. If you configure a `deferred` code update strategy, when you deploy a code change, Cloudflare will wait for an active Durable Object to become inactive or to "hibernate", and only once this happens or the maximum delay is exceeded, Cloudflare will create a fresh isolate that runs the new version of your code, discarding any in-memory state.
+
+Just like other compute environments where compute instances do not live forever, you should persist any state that must be durable across code deployments to Durable Storage. Durable Objects makes this simple — each individual Durable Object has its own SQLite database that you can read from and write to synchronously.
 
 ## Access storage
 

src/content/docs/durable-objects/best-practices/websockets.mdx

@@ -715,9 +715,13 @@ Configure your Wrangler file with a Durable Object [binding](/durable-objects/ge
 
 A full example is available in [Build a WebSocket server](/durable-objects/examples/websocket-server/).
 
-:::caution[WebSocket disconnection on deploy]
+:::caution[WebSocket disconnection during code updates]
 
-Code updates disconnect all WebSockets. Deploying a new version restarts every Durable Object, which disconnects any existing connections.
+Connections accepted with the WebSocket Hibernation API remain connected when a Durable Object adopts new code after hibernating.
+
+A forced code update disconnects WebSockets attached to the running instance. This happens when a `deferred` code update's `max_delay` is reached before hibernation, or when the code update strategy is set to `immediate`. The Web Standard WebSocket API prevents hibernation, so its connections are disconnected when the code update is applied.
+
+Refer to [Defer code updates until hibernation](/durable-objects/deployments/durable-objects-code-updates/) for more information.
 
 :::
 

src/content/docs/durable-objects/concepts/durable-object-lifecycle.mdx

@@ -86,22 +86,26 @@ A Durable Object incurs charges only when it is **actively running in-memory**,
 
 Durable Objects will occasionally shut down and objects are restarted, which will run your Durable Object class constructor. This can happen for various reasons, including:
 
-- New Worker [deployments](/workers/versions-and-deployments/) with code updates
+- Worker code updates that use an `immediate` code update strategy, or a `deferred` strategy that reaches its `max_delay`
 - Lack of requests to an object following the state transitions documented above
 - Cloudflare updates to the Workers runtime system
 - Workers runtime decisions on where to host objects
 
 When a Durable Object is shut down, the object instance is automatically restarted and new requests are routed to the new instance. In-flight requests are handled as follows:
 
 - **HTTP & RPC requests**: In-flight requests are allowed to finish if they do not access a Durable Object's storage.  If a request attempts to access a Durable Object's storage, it will be stopped immediately and return an error to maintain Durable Objects global uniqueness property. When the Worker runtime system is being updated, in-flight requests have up to 30 seconds to complete.
-- **WebSocket connections**: WebSocket requests are terminated automatically during shutdown. This is so that the new instance can take over the connection as soon as possible.
+- **WebSocket connections**: When a Durable Object shuts down, WebSocket connections are terminated automatically. This allows the new instance to take over the connection as soon as possible.
 - **Other invocations (email, cron)**: Other invocations are treated similarly to HTTP requests.
 
 It is important to ensure that any services using Durable Objects are designed to handle the possibility of a Durable Object being shut down.
 
 ### Code updates
 
-When your Durable Object code is updated, your Worker and Durable Objects are released globally in an eventually consistent manner. This will cause a Durable Object to shut down, with the behavior described above. Updates can also create a situation where a request reaches a new version of your Worker in one location, and calls to a Durable Object still running a previous version elsewhere. Refer to [Code updates](/durable-objects/platform/known-issues/#code-updates) for more information about handling this scenario.
+[Deploying a new Worker version](/workers/versions-and-deployments/) is not delayed by a code update strategy — the deployment itself completes immediately. What a code update strategy controls is when each already-active Durable Object adopts that new version.
+
+A `deferred` code update strategy lets an active Durable Object keep serving requests, storage operations, and Hibernation API WebSockets on its current code until it hibernates, instead of shutting it down immediately. If the object is still active when `max_delay` is reached, Cloudflare shuts it down and applies the update.
+
+Refer to [Defer code updates until hibernation](/durable-objects/deployments/durable-objects-code-updates/) to configure a code update strategy and understand how it interacts with gradual deployments.
 
 ### Working without shutdown hooks
 

src/content/docs/durable-objects/reference/durable-object-gradual-deployments.mdx → src/content/docs/durable-objects/deployments/durable-object-gradual-deployments.mdx

@@ -3,7 +3,7 @@ pcx_content_type: navigation
 title: Gradual Deployments
 external_link: /workers/versions-and-deployments/gradual-deployments/#gradual-deployments-for-durable-objects
 sidebar:
-  order: 10
+  order: 2
 head: []
 description: Gradually deploy changes to Durable Objects.
 products: