Use Workers KV from Durable Objects
- On this page

Use Workers KV from Durable Objects

Read and write to/from Workers KV within a Durable Object

Last updated Oct 12, 2026 The following Worker script shows you how to configure a Durable Object to read from and/or write to a Workers KV namespace. This is useful when using a Durable Object to coordinate between multiple clients, and allows you to serialize writes to KV and/or broadcast a single read from KV to hundreds or thousands of clients connected to a single Durable Object using WebSockets.

Prerequisites:

A KV namespace created via the Cloudflare dashboard or the wrangler CLI.
A configured binding for the kv_namespace in the Cloudflare dashboard or Wrangler file.
A Durable Object namespace binding.

Configure your Wrangler file as follows:

{
    "$schema": "./node_modules/wrangler/config-schema.json",
    "name": "my-worker",
    "main": "src/index.ts",
    "upload_source_maps": true,
    "kv_namespaces": [
        {
            "binding": "YOUR_KV_NAMESPACE",
            "id": "<id_of_your_namespace>"
        }
    ],
    "durable_objects": {
        "bindings": [
            {
                "name": "YOUR_DO_CLASS",
                "class_name": "YourDurableObject"
            }
        ]
    }
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "my-worker"
main = "src/index.ts"
upload_source_maps = true

[[kv_namespaces]]
binding = "YOUR_KV_NAMESPACE"
id = "<id_of_your_namespace>"

[[durable_objects.bindings]]
name = "YOUR_DO_CLASS"
class_name = "YourDurableObject"

import { DurableObject } from "cloudflare:workers";

interface Env {
    YOUR_KV_NAMESPACE: KVNamespace;
    YOUR_DO_CLASS: DurableObjectNamespace;
}

export default {
    async fetch(req: Request, env: Env): Promise<Response> {
        // Assume each Durable Object is mapped to a roomId in a query parameter
        // In a production application, this will likely be a roomId defined by your application
        // that you validate (and/or authenticate) first.
        let url = new URL(req.url);
        let roomIdParam = url.searchParams.get("roomId");

        if (roomIdParam) {
            // Get a stub that allows you to call that Durable Object
            let durableObjectStub = env.YOUR_DO_CLASS.getByName(roomIdParam);

            // Pass the request to that Durable Object and await the response
            // This invokes the constructor once on your Durable Object class (defined further down)
            // on the first initialization, and the fetch method on each request.
            //
            // You could pass the original Request to the Durable Object's fetch method
            // or a simpler URL with just the roomId.
            let response = await durableObjectStub.fetch(`http://do/${roomId}`);

            // This would return the value you read from KV *within* the Durable Object.
            return response;
        }
    },
};

export class YourDurableObject extends DurableObject {
    constructor(
        public state: DurableObjectState,
        env: Env,
    ) {
        super(state, env);
    }

    async fetch(request: Request) {
        // Error handling elided for brevity.
        // Write to KV
        await this.env.YOUR_KV_NAMESPACE.put("some-key");

        // Fetch from KV
        let val = await this.env.YOUR_KV_NAMESPACE.get("some-other-key");

        return Response.json(val);
    }
}

from workers import DurableObject, Response, WorkerEntrypoint
from urllib.parse import urlparse, parse_qs

class Default(WorkerEntrypoint):
    async def fetch(self, req):
        # Assume each Durable Object is mapped to a roomId in a query parameter
        # In a production application, this will likely be a roomId defined by your application
        # that you validate (and/or authenticate) first.
        url = req.url
        parsed_url = urlparse(url)
        room_id_param = parse_qs(parsed_url.query).get('roomId', [None])[0]

        if room_id_param:
            # Get a stub that allows you to call that Durable Object
            durable_object_stub = self.env.YOUR_DO_CLASS.getByName(room_id_param)

            # Pass the request to that Durable Object and await the response
            # This invokes the constructor once on your Durable Object class (defined further down)
            # on the first initialization, and the fetch method on each request.
            #
            # You could pass the original Request to the Durable Object's fetch method
            # or a simpler URL with just the roomId.
            response = await durable_object_stub.fetch(f"http://do/{room_id_param}")

            # This would return the value you read from KV *within* the Durable Object.
            return response

class YourDurableObject(DurableObject):
    def __init__(self, state, env):
        super().__init__(state, env)

    async def fetch(self, request):
        # Error handling elided for brevity.
        # Write to KV
        await self.env.YOUR_KV_NAMESPACE.put("some-key", "some-value")

        # Fetch from KV
        val = await self.env.YOUR_KV_NAMESPACE.get("some-other-key")

        return Response.json(val)

Was this helpful?

YesNo

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/durable-objects/examples/use-kv-from-durable-objects/#page","headline":"Use Workers KV from Durable Objects","description":"Read and write to/from KV within a Durable Object","url":"https://developers.cloudflare.com/durable-objects/examples/use-kv-from-durable-objects/","inLanguage":"en","image":"https://developers.cloudflare.com/durable-objects/examples/use-kv-from-durable-objects/og.png?v=8ee05704f188758a","dateModified":"2026-10-12","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Build a WebSocket server using WebSocket Hibernation on Durable Objects and Workers. title: Build a WebSocket server with WebSocket Hibernation image: https://developers.cloudflare.com/durable-objects/examples/websocket-hibernation-server/og.png?v=7877994f4d9ae82b

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/durable-objects/llms.txt
Use this file to discover all available pages before exploring further.

Use Workers KV from Durable Objects

Use Workers KV from Durable Objects

On this page