How do I manage schema evolution for durable objects that persist over time? When I change a durable

Ssdr How do I manage schema evolution for durable objects that persist over time? Whe...

A

ajgeiss0702•3/3/25, 6:43 PM

I believe you would need to write your own system for detecting an older schema and updating it

Ssdr How do I manage schema evolution for durable objects that persist over time? Whe...

L

lambrospetrou•3/3/25, 7:43 PM

You can use this helper I made for SQL schema migrations: https://github.com/lambrospetrou/durable-utils?tab=readme-ov-file#sqlite-schema-migrations

If you control access to your DOs, run this in your constructor, otherwise right before accessing the SQLite database of your DO (it has in-memory caching so should be fast once there are no migrations to apply).

Regarding old DOs that are not running for many months, you can still use this helper, but you need to make sure they will apply the migrations (

runAll()

runAll()

runAll()

runAll()) before accessing the storage so that they have the latest schema.

If you want all your DOs to have the latest schema, to make sure they won't fail for a random DO months after you wrote them, then you need to write a bit of custom code to iterate over the relevant DOs and apply the migrations to them.

As long as your migrations are idempotent (e.g.

CREATE TABLE IF NOT EXISTS

CREATE TABLE IF NOT EXISTS

CREATE TABLE IF NOT EXISTS

CREATE TABLE IF NOT EXISTS vs

CREATE TABLE

CREATE TABLE

CREATE TABLE

CREATE TABLE), and are small enough (not data migrations) then you probably don't need to do eager migrations and wake up all your DOs.

S

sdrOP•3/3/25, 8:02 PM

Ok sweet, thanks for the share. Ill take a look

Llambrospetrou BTW, just to make sure people are on the same page. Right now SQLite DOs, do NOT...

B

Burrito•3/3/25, 10:57 PM

Any news from the team? Checked a project of mine just now and the dashboard numbers seem to still be way too high.

Original message was deleted

B

boop•3/4/25, 10:29 AM

https://tenor.com/view/shore-coast-never-ending-loop-infinite-gif-12230198

Tenor

B

BL22•3/4/25, 10:32 AM

Kkkkk

B

BL22•3/4/25, 10:32 AM

Chapei

C

CodingCoop | Co-Founder Nullshot•3/5/25, 1:08 PM

From my understanding, Durable Object Groups is still required if you want to scale websocket connections into the potentially tens of thousands with Durable Objects?

https://github.com/cloudflare/dog

GitHub

GitHub - cloudflare/dog: Durable Object Groups

Durable Object Groups. Contribute to cloudflare/dog development by creating an account on GitHub.

CCodingCoop | Co-Founder Nullshot From my understanding, Durable Object Groups is still required if you want to sc...

K

kchro3•3/5/25, 4:59 PM

whoa, this is cool. is this still supported? it looks like last commit was 6mo ago

I

iano•3/5/25, 5:55 PM

How does changing the constructor parameters of a Durable Object work. For example if I pass in a database connection string, if I then change that string and call the same DurableObject with the new string will it re-construct it? Or only once its kicked out of memory?

Iiano How does changing the constructor parameters of a Durable Object work. For examp...

L

lambrospetrou•3/5/25, 7:26 PM

You cannot pass anything to the DO constructor, it's called by the runtime, not your code.

N

Nisar446•3/5/25, 7:27 PM

Hi

N

Nisar446•3/5/25, 7:28 PM

:MeowHeartCloudflare:

CCodingCoop | Co-Founder Nullshot From my understanding, Durable Object Groups is still required if you want to sc...

1

1984 Ford Laser•3/5/25, 8:50 PM

Has anyone used this at all? Looks really cool

Llambrospetrou You cannot pass anything to the DO constructor, it's called by the runtime, not ...

I

iano•3/5/25, 9:59 PM

errr the environment

I

iano•3/5/25, 9:59 PM

so if you deploy with a new environment I mean

Iiano errr the environment

L

lambrospetrou•3/5/25, 10:01 PM

For the

env

env

to change you make a new deployment, so your DO will restart and the constructor will rerun.

I

iano•3/5/25, 10:01 PM

got it, thanks!

F

Fernando Barroso•3/6/25, 1:54 AM

Anyone know if we could get a DO’s load from an internal API as detailed in the queues article (highlighted above). Or is this something that was custom-built?

F

Fernando Barroso•3/6/25, 1:55 AM

(By load I mean requests per second, I know we could get database size using the sql storage API)

U

Unsmart•3/6/25, 1:58 AM

That is something they would have done in the DO's custom code I imagine, and not something just available to all DOs created

11984 Ford Laser Has anyone used this at all? Looks really cool

C

CodingCoop | Co-Founder Nullshot•3/6/25, 9:18 AM

Im using it right now, its working fine and at scale (10K CCU test). I may do a PR to give it hybernation support as the websockets do not support hybernation yet.

Kkchro3 whoa, this is cool. is this still supported? it looks like last commit was 6mo a...

C

CodingCoop | Co-Founder Nullshot•3/6/25, 9:18 AM

It still works for sure, not sure if its supported though.

CCodingCoop | Co-Founder Nullshot Im using it right now, its working fine and at scale (10K CCU test). I may do a ...

1

1984 Ford Laser•3/6/25, 9:19 AM

Ohhh that is definitely a necessity for my setup, but otherwise it looks super interesting. Will keep an eye out for a PR

UUnsmart That is something they would have done in the DO's custom code I imagine, and no...

F

Fernando Barroso•3/6/25, 1:11 PM

thanks for the response! Any insight as to how they would've built this by chance? Maybe using in-memory state I'm guessing, similar to a rate limiting DO?

FFernando Barroso thanks for the response! Any insight as to how they would've built this by chanc...

L

lambrospetrou•3/6/25, 2:15 PM

What is the metric you are interested in to decide if you need to scale out?
I am working on a dynamic sharding abstraction so having some concrete needs is useful. Unofficially, for my

durable-utils

durable-utils

durable-utils

durable-utils library.

F

Fernando Barroso•3/6/25, 2:23 PM

I would use both, the size of my database (given the tiny 1 GB limit for now) and requests per second (given the traffic limit as well of 1,000 req per sec)

I

Iggy•3/6/25, 5:13 PM

why does it sometimes take ~500ms to get a stub even with frequent traffic to it?

I

Iggy•3/6/25, 5:19 PM

it looks like it's because of this: https://github.com/cloudflare/workers-sdk/issues/2700. are there any workarounds or do you just have to accept ~500ms cold starts?

GitHub

Issues · cloudflare/workers-sdk

Home to Wrangler, the CLI for Cloudflare Workers® - Issues · cloudflare/workers-sdk

I

Iggy•3/6/25, 5:22 PM

ah nvm - looks a bit extreme on my end with some db seeding code

M

mau•3/7/25, 9:44 PM

Cannot create binding for class 'MyYServer' because it is not currently configured to implement Durable Objects. Ensure a --new-class migration has been applied to it. [code: 10061]

Getting this error after adding a new class.

Mmau Cannot create binding for class 'MyYServer' because it is not currently configur...

H

Hard@Work•3/7/25, 9:47 PM

Do you have a migration in your

wrangler

wrangler

config that includes the new class?

M

mau•3/7/25, 10:21 PM

Yes, I had… after a lot of tinkering… finally added v2 and added that with v2 tag and it worked.

H

hunt•3/8/25, 8:58 AM

Cool little utility I wrote to make accessing DO's easier in case anyone's interested:

import { DurableObject as DurableObjectPrimitive } from "cloudflare:workers";

const iife = <T>(fn: () => T): T => fn();

export function DurableObject<TEnv>(accessor: keyof TEnv) {
  return class DurableObject extends DurableObjectPrimitive<TEnv> {
    /**
     * Retrieves a durable object stub for a given id.
     *
     * @template T - The type of the DurableObject.
     * @param {TEnv} env - The env object containing the durable object's namespace.
     * @param {DurableObjectId | string} [id] - The id of the DurableObject. If not provided, `newUniqueId()` will be used.
     * @returns {DurableObjectStub<T>} The DurableObjectStub for the given id.
     */
    static getStub<T extends DurableObjectPrimitive>(
      this: { new (...args: any[]): T },
      env: TEnv,
      id?: DurableObjectId | string
    ): DurableObjectStub<T> {
      const namespace = env[accessor] as DurableObjectNamespace<T>;
      const stubId = iife(() => {
        if (!id) return namespace.newUniqueId();
        if (typeof id === "string") {
          // Check if the provided id is a string representation of the
          // 256-bit Durable Object ID
          if (id.match(/^[0-9a-f]{64}$/)) return namespace.idFromString(id);
          else return namespace.idFromName(id);
        }
        return id;
      });
      const stub = namespace.get(stubId);
      return stub;
    }
  };
}

import { DurableObject as DurableObjectPrimitive } from "cloudflare:workers";

const iife = <T>(fn: () => T): T => fn();

export function DurableObject<TEnv>(accessor: keyof TEnv) {
  return class DurableObject extends DurableObjectPrimitive<TEnv> {
    /**
     * Retrieves a durable object stub for a given id.
     *
     * @template T - The type of the DurableObject.
     * @param {TEnv} env - The env object containing the durable object's namespace.
     * @param {DurableObjectId | string} [id] - The id of the DurableObject. If not provided, `newUniqueId()` will be used.
     * @returns {DurableObjectStub<T>} The DurableObjectStub for the given id.
     */
    static getStub<T extends DurableObjectPrimitive>(
      this: { new (...args: any[]): T },
      env: TEnv,
      id?: DurableObjectId | string
    ): DurableObjectStub<T> {
      const namespace = env[accessor] as DurableObjectNamespace<T>;
      const stubId = iife(() => {
        if (!id) return namespace.newUniqueId();
        if (typeof id === "string") {
          // Check if the provided id is a string representation of the
          // 256-bit Durable Object ID
          if (id.match(/^[0-9a-f]{64}$/)) return namespace.idFromString(id);
          else return namespace.idFromName(id);
        }
        return id;
      });
      const stub = namespace.get(stubId);
      return stub;
    }
  };
}

import { DurableObject as DurableObjectPrimitive } from "cloudflare:workers";

const iife = <T>(fn: () => T): T => fn();

export function DurableObject<TEnv>(accessor: keyof TEnv) {
  return class DurableObject extends DurableObjectPrimitive<TEnv> {
    /**
     * Retrieves a durable object stub for a given id.
     *
     * @template T - The type of the DurableObject.
     * @param {TEnv} env - The env object containing the durable object's namespace.
     * @param {DurableObjectId | string} [id] - The id of the DurableObject. If not provided, `newUniqueId()` will be used.
     * @returns {DurableObjectStub<T>} The DurableObjectStub for the given id.
     */
    static getStub<T extends DurableObjectPrimitive>(
      this: { new (...args: any[]): T },
      env: TEnv,
      id?: DurableObjectId | string
    ): DurableObjectStub<T> {
      const namespace = env[accessor] as DurableObjectNamespace<T>;
      const stubId = iife(() => {
        if (!id) return namespace.newUniqueId();
        if (typeof id === "string") {
          // Check if the provided id is a string representation of the
          // 256-bit Durable Object ID
          if (id.match(/^[0-9a-f]{64}$/)) return namespace.idFromString(id);
          else return namespace.idFromName(id);
        }
        return id;
      });
      const stub = namespace.get(stubId);
      return stub;
    }
  };
}

import { DurableObject as DurableObjectPrimitive } from "cloudflare:workers";

const iife = <T>(fn: () => T): T => fn();

export function DurableObject<TEnv>(accessor: keyof TEnv) {
  return class DurableObject extends DurableObjectPrimitive<TEnv> {
    /**
     * Retrieves a durable object stub for a given id.
     *
     * @template T - The type of the DurableObject.
     * @param {TEnv} env - The env object containing the durable object's namespace.
     * @param {DurableObjectId | string} [id] - The id of the DurableObject. If not provided, `newUniqueId()` will be used.
     * @returns {DurableObjectStub<T>} The DurableObjectStub for the given id.
     */
    static getStub<T extends DurableObjectPrimitive>(
      this: { new (...args: any[]): T },
      env: TEnv,
      id?: DurableObjectId | string
    ): DurableObjectStub<T> {
      const namespace = env[accessor] as DurableObjectNamespace<T>;
      const stubId = iife(() => {
        if (!id) return namespace.newUniqueId();
        if (typeof id === "string") {
          // Check if the provided id is a string representation of the
          // 256-bit Durable Object ID
          if (id.match(/^[0-9a-f]{64}$/)) return namespace.idFromString(id);
          else return namespace.idFromName(id);
        }
        return id;
      });
      const stub = namespace.get(stubId);
      return stub;
    }
  };
}

interface Env {
  FOO_OBJECT: DurableObjectNamespace<FooObject>;
  BAR_OBJECT: DurableObjectNamespace<BarObject>;
}

export class FooObject extends DurableObject<Env>("FOO_OBJECT") {
  getFoo() {
    return "foo!";
  }
}

export class BarObject extends DurableObject<Env>("BAR_OBJECT") {
  getBar() {
    return 41;
  }
}

// example usage:
const fooStub = FooObject.getStub(env, "123");
const barStub = BarObject.getStub(env, "123");

fooStub.getFoo(); // () -> Promise<string>
barStub.getBar(); // () -> Promise<number>

interface Env {
  FOO_OBJECT: DurableObjectNamespace<FooObject>;
  BAR_OBJECT: DurableObjectNamespace<BarObject>;
}

export class FooObject extends DurableObject<Env>("FOO_OBJECT") {
  getFoo() {
    return "foo!";
  }
}

export class BarObject extends DurableObject<Env>("BAR_OBJECT") {
  getBar() {
    return 41;
  }
}

// example usage:
const fooStub = FooObject.getStub(env, "123");
const barStub = BarObject.getStub(env, "123");

fooStub.getFoo(); // () -> Promise<string>
barStub.getBar(); // () -> Promise<number>

interface Env {
  FOO_OBJECT: DurableObjectNamespace<FooObject>;
  BAR_OBJECT: DurableObjectNamespace<BarObject>;
}

export class FooObject extends DurableObject<Env>("FOO_OBJECT") {
  getFoo() {
    return "foo!";
  }
}

export class BarObject extends DurableObject<Env>("BAR_OBJECT") {
  getBar() {
    return 41;
  }
}

// example usage:
const fooStub = FooObject.getStub(env, "123");
const barStub = BarObject.getStub(env, "123");

fooStub.getFoo(); // () -> Promise<string>
barStub.getBar(); // () -> Promise<number>

interface Env {
  FOO_OBJECT: DurableObjectNamespace<FooObject>;
  BAR_OBJECT: DurableObjectNamespace<BarObject>;
}

export class FooObject extends DurableObject<Env>("FOO_OBJECT") {
  getFoo() {
    return "foo!";
  }
}

export class BarObject extends DurableObject<Env>("BAR_OBJECT") {
  getBar() {
    return 41;
  }
}

// example usage:
const fooStub = FooObject.getStub(env, "123");
const barStub = BarObject.getStub(env, "123");

fooStub.getFoo(); // () -> Promise<string>
barStub.getBar(); // () -> Promise<number>

A

Ashley•3/8/25, 10:10 AM

Someone asked me the other day, and now I’m curious, what’s the max number of concurrent WebSocket connections that a DO can have? Assuming it’s using hibernation, and to keep it simple let’s say each message sent is just relayed to all connected clients so nothing complex or computationally-heavy.

A

Ashley•3/8/25, 10:13 AM

My guess was that it’s effectively unlimited, but it’s “gated” by the fact it’s single-threaded so it can only process so much (e.g. if you had 100,000 clients, and they are all sending messages, there’s likely no way the single thread can process and broadcast all these messages without falling behind)

1

1984 Ford Laser•3/8/25, 10:56 AM

https://developers.cloudflare.com/durable-objects/api/state/#:~:text=The%20WebSocket%20Hibernation%20API%20permits,practical%20number%20of%20simultaneous%20connections.

The maximum limit of WebSocket connections per DO is 32768

Edit: with Hibernation

A

Ashley•3/8/25, 12:08 PM

Oh nice, thank you!

AAshley Oh nice, thank you!

M

Milan•3/8/25, 5:26 PM

That's a hard limit, but of course it depends on how much memory your application is using

, if you run out of memory before you have 32ki connections you won't even reach that limit.

M

Milan•3/8/25, 5:26 PM

You probably don't want that many connections to a single DO anyways though, I would try to build a tree where your clients connect to leaf nodes, and the leaf nodes connect to a root

AAshley Someone asked me the other day, and now I’m curious, what’s the max number of co...

C

CodingCoop | Co-Founder Nullshot•3/9/25, 12:03 AM

Website says 1000 rps under limits somewhere and there is a DOG service that allows for scaling DO horizontally - with DOs having 128mb memory to play with it wouldn’t be able to handle tens of thousands.

https://developers.cloudflare.com/durable-objects/platform/limits/

I have leaned into this project to help me scale to 10k:

https://github.com/cloudflare/dog

Cloudflare Docs

Limits · Cloudflare Durable Objects docs

Durable Objects are only available on the Workers Paid plan. Durable Objects limits are the same as Workers Limits, as well as the following limits that are specific to Durable Objects:

GitHub

GitHub - cloudflare/dog: Durable Object Groups

Durable Object Groups. Contribute to cloudflare/dog development by creating an account on GitHub.

CCodingCoop | Co-Founder Nullshot Website says 1000 rps under limits somewhere and there is a DOG service that all...

M

mihaaai•3/9/25, 11:02 AM

The 1000rps is for requests, not websocket messages

AAshley Someone asked me the other day, and now I’m curious, what’s the max number of co...

M

mihaaai•3/9/25, 11:06 AM

With hibernation the DO server should be able to hold up to 32k client connections at a time and broadcast between each-others

D

DaniFoldi•3/9/25, 11:01 PM

although if you're broadcasting to all of them, from my experience it can't really handle more than a few thousand, so I'd recommend soft limiting to 2-4k

D

DaniFoldi•3/9/25, 11:02 PM

and at around 20-25k connections it became pretty unreliable

D

DaniFoldi•3/9/25, 11:02 PM

(these are from my testing done a few months ago)

DDaniFoldi although if you're broadcasting to all of them, from my experience it can't real...

A

akazwz•3/10/25, 3:33 PM

single Do right ?

Aakazwz single Do right ?

D

DaniFoldi•3/10/25, 3:33 PM

correct

R

rh•3/12/25, 10:45 AM

Is something like https://github.com/cloudflare/workers-rs also available for C++? Or does anybody have an example on how to use the SQLite storage API in a C++ to WASM build?

GitHub

GitHub - cloudflare/workers-rs: Write Cloudflare Workers in 100% Ru...

Write Cloudflare Workers in 100% Rust via WebAssembly - cloudflare/workers-rs

L

Larry•3/13/25, 4:09 PM

Is there any way to know the "name" as in "foo" in this example,

env.MY_DURABLE_OBJECT.idFromName("foo")

env.MY_DURABLE_OBJECT.idFromName("foo")

, once inside of a DO instance? At one point I know the answer used to be "no" but I'm wondering if this has changed.

How do I manage schema evolution for durable objects that persist over time? When I change a durable

Similar Threads

Similar Threads

Similar Threads