Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 4 additions & 8 deletions src/content/docs/durable-objects/api/storage-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,6 @@ The Durable Object Storage API allows <GlossaryTooltip term="Durable Object">Dur

The Durable Object Storage API comes with several methods, including SQL, point-in-time recovery (PITR), key-value (KV), and alarm APIs. Available API methods depend on the storage backend for a Durable Objects class, either [SQLite](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class) or [KV](/durable-objects/reference/durable-objects-migrations/#create-durable-object-class-with-key-value-storage).

:::note[Recommended SQLite-backed Durable Objects]
Cloudflare recommends all new Durable Object classes use the [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class).

The [key-value storage backend](/durable-objects/reference/durable-objects-migrations/#create-durable-object-class-with-key-value-storage) remains for backwards compatibility, and a migration path from KV storage to SQLite storage for existing Durable Object classes will be available in the future.
:::

<Render file="do-sqlite-storage-no-bill-note"/>

| Methods <sup>1</sup> | SQLite-backed Durable Object class | KV-backed Durable Object class |
| ----------------------- | ---------------------------- | ------------------------ |
| SQL API | ✅ | ❌ |
Expand All @@ -43,6 +35,10 @@ The [key-value storage backend](/durable-objects/reference/durable-objects-migra

</Details>

<Render file="recommend-sqlite-do" product="durable-objects"/>

<Render file="do-sqlite-storage-no-bill-note"/>

## Access storage

Durable Objects gain access to Storage API via the `DurableObjectStorage` interface and accessed by the `DurableObjectState::storage` property. This is frequently accessed via `this.ctx.storage` with the `ctx` parameter passed to the Durable Object constructor.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,7 @@ A Durable Object's [in-memory state](/durable-objects/reference/in-memory-state/

## Access storage

:::note[Recommended SQLite-backed Durable Objects]
Cloudflare recommends all new Durable Object classes use the [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class).

The [key-value storage backend](/durable-objects/reference/durable-objects-migrations/#create-durable-object-class-with-key-value-storage) remains for backwards compatibility, and a migration path from KV storage to SQLite storage for existing Durable Object classes will be available in the future.
:::
<Render file="recommend-sqlite-do" product="durable-objects"/>

<Render file="do-sqlite-storage-no-bill-note"/>

Expand Down Expand Up @@ -88,7 +84,7 @@ export class MyDurableObject extends DurableObject<Env> {
async clearDo():Promise<void> {
// If you've configured a Durable Object alarm
await this.ctx.storage.deleteAlarm();

// This will delete all the storage associated with this Durable Object instance
// This will also delete the Durable Object instance itself
await this.ctx.storage.deleteAll();
Expand Down Expand Up @@ -152,7 +148,7 @@ for (let row of cursor) {
}
```

You can represent the shape of any result type you wish, including more complex types. If you are performing a
You can represent the shape of any result type you wish, including more complex types. If you are performing a
`JOIN` across multiple tables, you can compose a type that reflects the results of your queries.

## Indexes in SQLite
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -83,11 +83,7 @@ new_sqlite_classes = ["DurableObjectAClass"]

### Create Durable Object class with key-value storage

:::note[Recommended SQLite-backed Durable Objects]
Cloudflare recommends all new Durable Object classes use the [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class).

The key-value storage backend remains for backwards compatibility.
:::
<Render file="recommend-sqlite-do" product="durable-objects"/>

Use `new_classes` on the migration in your Worker's Wrangler file to create a Durable Object class with the key-value storage backend:

Expand Down Expand Up @@ -269,7 +265,7 @@ transferred_classes = [{from = "DurableObjectExample", from_script = "OldWorkerS

- Migration tags are treated like unique names and are used to determine which migrations have already been applied. Once a given Worker code has a migration tag set on it, all future Worker code deployments must include a migration tag.

- The migration list is an ordered array of tables, specified as a key in your Wrangler configuration file.
- The migration list is an ordered array of tables, specified as a key in your Wrangler configuration file.

- You can define the migration for each environment, as well as at the top level.
- Top-level migration is specified at the top-level `migrations` key in the Wrangler configuration file.
Expand Down
11 changes: 11 additions & 0 deletions src/content/partials/durable-objects/recommend-sqlite-do.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
---
{}
---

:::note[Recommended SQLite-backed Durable Objects]
Cloudflare recommends all new Durable Object namespaces use the [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#create-sqlite-backed-durable-object-class). These Durable Objects can continue to use storage [key-value API](/durable-objects/api/storage-api/#kv-api).

Additionally, SQLite-backed Durable Objects allow you to store more types of data (such as tables), and offers Point In Time Recovery API which can restore a the Durable Object's embedded SQLite database contents (both SQL data and key-value data) to any point in the past 30 days.

The [key-value storage backend](/durable-objects/reference/durable-objects-migrations/#create-durable-object-class-with-key-value-storage) remains for backwards compatibility, and a migration path from KV storage backend to SQLite storage backend for existing Durable Object namespaces will be available in the future.
:::
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,4 @@ Each method is implicitly wrapped inside a transaction, such that its results ar
| KV API | ✅ | ✅ |
| Alarms API | ✅ | ✅ |

:::note[Recommended SQLite-backed Durable Object]
We recommend using SQLite-backed Durable Object over key-value backed Durable Object. SQLite-backed Durable Objects allow you to store more types of data (such as tables), and offers Point In Time Recovery API which can restore a the Durable Object's embedded SQLite database contents (both SQL data and key-value data) to any point in the past 30 days.
:::
<Render file="recommend-sqlite-do" product="durable-objects"/>
Loading