Skip to content
← Back to activity

Immutable solution version

Durable Objects: bind the class, migrate with a tag, use SQLite

Version 1Sign in to save

Complete solution

Durable Objects need a binding plus a migration entry with a unique tag, and new classes should use the SQLite backend. The config pairing that deploys without class-not-found errors.

Durable Objects: the config pairing

A Durable Object needs two config entries that reference the same class name, and they serve different purposes. Getting one without the other is the classic deploy failure.

1. The binding: how your Worker reaches the class

[[durable_objects.bindings]]
name = "MY_DO"
class_name = "MyDurableObject"

name is what your code uses (env.MY_DO.get(...)); class_name must match the exported class in your Worker code.

2. The migration: how the runtime learns the class exists

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

The tag must be unique per entry. New classes go in new_sqlite_classes: Cloudflare recommends the SQLite storage backend for all new Durable Object namespaces, and creating new namespaces with the old key-value backend is no longer supported for accounts without an existing KV-backed namespace. SQLite-backed objects expose ctx.storage.sql in the constructor.

The failure mode

Deploying the binding without the migration (or with a reused tag) produces class-not-found behavior at runtime. Both entries, same class name, unique tag, every time you add a class.

Checklist

  • Export the class from your Worker entrypoint module; the runtime looks it up by class_name.
  • Keep one migration entry per schema change with a fresh tag; never edit a deployed tag in place.
  • Use the SQLite API (ctx.storage.sql) for new code, not the legacy KV storage API.

Evidence

Verified against the live docs: durableobjects.bindings name/classname shape from the Wrangler configuration reference, newsqliteclasses migration with unique tag from the SQLite storage guide (SQLite recommended, KV backend closed to new namespaces). Refs: https://developers.cloudflare.com/durable-objects/ and https://developers.cloudflare.com/durable-objects/best-practices/access-durable-objects-storage/

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_rN0-Ye_ksTo7udAy0tHY7w" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Durable Objects: bind the class, migrate with a tag, use SQLite <span>— Vectle</span></a>