skip to content

In Wrangler 4, how do you declare a new SQLite-backed Durable Object class, and why can't an existing class change its storage backend?

level: middleimportance: should knowfreq 35%

answer

  1. binding and lifecycle are separate
  2. a declarative map keyed by class
  3. storage set to sqlite
  4. the older tagged migrations array
  5. backend fixed at provisioning

basics

~20 s

Bind the class under durable_objects.bindings and declare it in the exports map with "type": "durable-object" and "storage": "sqlite"; older Workers use a migrations entry with new_sqlite_classes. The backend is fixed when the namespace is first created.

solid answer

~50 s

A Durable Object class needs two things in the Wrangler file. The binding (`durable_objects.bindings` with `name` and `class_name`) gives code an `env` handle. The lifecycle declaration tells Cloudflare to provision a namespace. Since Wrangler 4.107.0, the declarative way is the `exports` map: `"TicketEvent": { "type": "durable-object", "storage": "sqlite" }`, reconciled against your code and the existing namespaces on each `wrangler deploy`. Workers that started earlier use the `migrations` array, with a tagged entry listing the class in `new_sqlite_classes`. That flow is now called legacy but is still supported, and a Worker declares its Durable Object classes through one flow or the other, never both. The backend is chosen when the namespace is provisioned and is immutable: `exports` rejects a switch with `storage_type_mismatch`, and `new_sqlite_classes` on an already-deployed class fails. In-place migration from the key-value backend is not available yet.

code

json · 11 lines
json
{
  "name": "tickets",
  "main": "src/index.js",
  "compatibility_date": "2026-10-01",
  "durable_objects": {
    "bindings": [{ "name": "TICKETS", "class_name": "TicketEvent" }]
  },
  "exports": {
    "TicketEvent": { "type": "durable-object", "storage": "sqlite" }
  }
}

go deeper

for a junior

Recall that a Durable Object class needs a binding plus a lifecycle entry, and that new classes declare storage as sqlite in the exports map.

for a middle

Explain the exports states, the legacy migrations array with new_sqlite_classes and new_classes, why the two flows are exclusive, and why the backend cannot change once provisioned.

for a senior

Show safe lifecycle changes: tombstones that destroy data, the three-deploy rename, external bindings that block a delete, and what the local SQL-not-enabled error is telling you.

for a principal

Decide when a team moves existing Workers from migrations to exports, and who reviews tombstones, since one wrong deleted entry erases every object of a class.

## Two halves: binding and lifecycle A **Durable Object namespace** is the set of all objects of one class. Getting one running takes two separate declarations in the Wrangler configuration file: - a **binding** in `durable_objects.bindings`, with `name` (the `env` property, such as `TICKETS`) and `class_name` (the exported class), so Worker code can reach the namespace; - a **lifecycle declaration**, which tells Cloudflare to create the namespace, and with which storage backend. The binding alone provisions nothing. If a class has a binding but no lifecycle entry, Wrangler warns that it has "no live `exports` entry" and prints the snippet to add. Under `wrangler dev` such a class runs without SQL, so `ctx.storage.sql.exec()` throws `SQL is not enabled for this Durable Object class`. ## The exports map Since Wrangler 4.107.0, the `exports` field is the **declarative** lifecycle. Each key is a class name, and its value describes the desired state: | `state` | Meaning | Required fields | | --- | --- | --- | | `created` (or omitted) | a live class | `storage` | | `deleted` | remove the namespace and all its data | none | | `renamed` | move the data to another class name | `renamed_to` | | `transferred` | hand the namespace to another Worker | `transferred_to` | | `expecting-transfer` | receive a namespace from another Worker | `storage`, `transfer_from` | On `wrangler deploy`, Cloudflare compares three things: the classes your code exports, what `exports` declares, and the namespaces already provisioned. It then creates, renames or deletes namespaces and prints a reconciliation summary. New namespaces created this way always use `"storage": "sqlite"`; `"legacy-kv"` is accepted only for a namespace that already uses the key-value backend. ## The legacy migrations array Workers created before `exports` declare lifecycle as an ordered list of tagged steps: - `tag`: a unique label for the step, applied once; - `new_sqlite_classes`: classes created with the SQLite backend; - `new_classes`: classes created with the key-value backend, which accounts without an existing key-value-backed namespace can no longer create; - `renamed_classes` (`from` and `to`) and `deleted_classes` for later changes. The documentation now labels this whole array **legacy** while keeping it fully supported. A Wrangler file that declares Durable Object classes in both `migrations` and `exports` is rejected with "`migrations` and `exports` are mutually exclusive". Moving an existing Worker from one to the other follows its own documented procedure. ## Why the backend is fixed The storage backend is a property of the namespace, chosen when it is provisioned, and every object in it stores data in that format. So: - in `exports`, changing a provisioned namespace between `sqlite` and `legacy-kv` fails with `storage_type_mismatch`; - in `migrations`, listing an already-deployed class in a later `new_sqlite_classes` step fails; - the only way to "switch" today is to delete the namespace and create it again, losing its data; an in-place path from key-value to SQLite has been promised for the future. Ordinary code changes need none of this. Deploying new code for an existing class, even code that reads storage differently, needs no lifecycle change; keeping that code compatible with stored data is your job. ## Lifecycle changes and gradual deployments - `wrangler versions upload` carries `exports` along, but lifecycle changes are applied only when a version is deployed with `wrangler versions deploy` or `wrangler deploy`. - A percentage split between two versions that disagree about `exports` is rejected: deploy the version that changes `exports` at 100% first, then split traffic. - `wrangler dev` reads the SQLite storage setting from `exports`, so an `exports`-only Worker gets the right local storage without a `migrations` block. ## Destructive changes, carefully 1. A `deleted` tombstone permanently removes the namespace and every object's data; there is no trash. The class must be gone from your code, and the deploy is blocked while another Worker still binds to it. 2. A rename needs the `renamed` tombstone plus a live entry for the new name. The docs recommend three deploys, re-exporting the class under its old name until the rename has rolled out, so no request hits a missing class. 3. Copy out any data you need before deploying a tombstone.

  • Does changing how a Durable Object class reads its storage need a new exports or migrations change?
    No. A lifecycle change is only for creating, deleting, renaming or transferring a class. New code for an existing class ships with a plain `wrangler deploy`, and the same objects keep their data. Making the new code understand data the old code wrote, for example with a schema step in the constructor, is the developer's job.
  • What does a deleted tombstone in exports do, and what blocks it?
    It removes the class's namespace and all stored data permanently. Cloudflare refuses it while the class is still exported by your code, and while another Worker in the account binds to it (the deploy fails with `tombstone_delete_blocked_by_external_bindings`). Once applied, the stale tombstone shows up in `removable_entries` and can be dropped from the file.
  • Why do the docs suggest three deploys for renaming a Durable Object class?
    The namespace's class pointer and the newly deployed code do not switch at exactly the same instant. Deploy one adds the new class and re-exports it under the old name. Deploy two adds the `renamed` tombstone with `renamed_to` and the live entry for the new name. Deploy three removes the alias. No request ever lands on a class name that does not exist.

  • A new Durable Object class still needs new_classes in a migrations entry.
  • Adding an existing key-value-backed class to new_sqlite_classes converts it in place.
  • Every code change to a Durable Object class needs a new migration tag.
  • A durable_objects binding on its own provisions the class's storage.
  • migrations and exports can be kept side by side during a transition.
  • A deleted tombstone archives the namespace's data so it can be restored.

Assumes Wrangler 4.107.0 or later, which added the declarative exports map; the docs now call the older migrations array the legacy flow, still supported but not combinable with exports.