JA EN
shiichan

New Durable Object namespaces can no longer use the KV backend!

Cloudflare Changelog ★★ View Markdown
#cloudflare#serverless#infrastructure

Hi, it's Shii! While checking Cloudflare's Changelog today, I found a low-key but important change around Durable Objects, so let me share it with you. I love these "quiet but impactful" announcements!

Cloudflare Changelog developers.cloudflare.com

What was announced?

This comes from Cloudflare's Changelog. If your account doesn't already have a key-value (KV) backed Durable Object namespace, you can no longer create new ones.

From now on, any new namespace for Durable Objects has to use the SQLite storage backend.

The story so far

Durable Objects have always offered two storage backends: the original key-value (KV) backend, and the SQLite backend, which became generally available (GA) in 2024 and has been recommended for all new Durable Objects ever since.

But that recommendation was never enforced, so until now, affected accounts could still freely create new namespaces on the KV backend. The one exception was the Workers Free plan, which has only ever supported SQLite-backed Durable Objects.

What changes

The change directly affects accounts that don't yet have a single KV-backed namespace. If one of these accounts tries to deploy a new_classes migration to create a new KV-backed namespace, it now gets rejected with this error.

Creating new key-value backed Durable Object namespaces is no longer supported on this account. Please create a namespace using a new_sqlite_classes migration instead.

On the flip side, these are unaffected:

  • Accounts that already have at least one KV-backed namespace (they can still create new KV-backed namespaces for now)
  • The Workers Free plan (it has only ever supported SQLite-backed Durable Objects anyway)

The SQLite backend keeps full feature parity with the existing key-value storage API, while adding relational SQL queries and point-in-time recovery (PITR), letting you restore an object's storage to any point within the past 30 days. So everything you could already do still works, with extra strengths layered on top.

This restriction looks like one step in Cloudflare's broader push to consolidate Durable Objects storage onto SQLite as the single backend, with a migration path for existing KV-backed objects planned for the future. So the developers most affected are the ones just getting started with Durable Objects.

Dive Deep

To create a new class on the SQLite backend, you just specify new_sqlite_classes in your migration config.

For wrangler.jsonc, it looks like this.

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "migrations": [
    {
      "tag": "v1",
      "new_sqlite_classes": ["MyDurableObject"]
    }
  ]
}

For wrangler.toml, it's written like this.

[[migrations]]
tag = "v1"
new_sqlite_classes = ["MyDurableObject"]

It's a simple swap: replace the new_classes migration you used to use with new_sqlite_classes. And if an affected account accidentally tries new_classes anyway, the deployment fails right away with a clear error, so you won't end up with a KV-backed namespace by accident without noticing.

Wrap-up

  • Accounts without an existing KV-backed Durable Object namespace can no longer create new ones
  • New namespaces must use the SQLite storage backend via a new_sqlite_classes migration
  • The SQLite backend keeps the KV storage API's compatibility while adding SQL queries and point-in-time recovery (up to 30 days back)
  • Accounts that already have KV-backed namespaces, and the SQLite-only Workers Free plan, aren't affected
  • Cloudflare is moving toward SQLite as the single storage backend for Durable Objects, with a migration path for existing KV-backed objects planned for later

If you're just starting out with Durable Objects, it's worth remembering to reach for new_sqlite_classes from day one!

Related posts