From be1b068c08178dafc38dd15be586f71dc75203b5 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Tue, 20 May 2025 17:10:10 +0100 Subject: [PATCH 1/4] Changing SQLite-backed DO recommendation into partial --- src/content/docs/durable-objects/api/storage-api.mdx | 12 ++++-------- .../access-durable-objects-storage.mdx | 10 +++------- .../reference/durable-objects-migrations.mdx | 8 ++------ .../partials/durable-objects/recommend-sqlite-do.mdx | 11 +++++++++++ .../partials/durable-objects/storage-intro-text.mdx | 4 +--- 5 files changed, 21 insertions(+), 24 deletions(-) create mode 100644 src/content/partials/durable-objects/recommend-sqlite-do.mdx diff --git a/src/content/docs/durable-objects/api/storage-api.mdx b/src/content/docs/durable-objects/api/storage-api.mdx index d63abdadbadab0..7a7e02aa614dba 100644 --- a/src/content/docs/durable-objects/api/storage-api.mdx +++ b/src/content/docs/durable-objects/api/storage-api.mdx @@ -18,14 +18,6 @@ The Durable Object Storage API allows 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. -::: - - - | Methods 1 | SQLite-backed Durable Object class | KV-backed Durable Object class | | ----------------------- | ---------------------------- | ------------------------ | | SQL API | ✅ | ❌ | @@ -43,6 +35,10 @@ The [key-value storage backend](/durable-objects/reference/durable-objects-migra + + + + ## 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. diff --git a/src/content/docs/durable-objects/best-practices/access-durable-objects-storage.mdx b/src/content/docs/durable-objects/best-practices/access-durable-objects-storage.mdx index 118b39c53fcb46..717470d639deb7 100644 --- a/src/content/docs/durable-objects/best-practices/access-durable-objects-storage.mdx +++ b/src/content/docs/durable-objects/best-practices/access-durable-objects-storage.mdx @@ -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. -::: + @@ -88,7 +84,7 @@ export class MyDurableObject extends DurableObject { async clearDo():Promise { // 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(); @@ -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 diff --git a/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx b/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx index 57be9a90813b01..f557f9085af2c4 100644 --- a/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx +++ b/src/content/docs/durable-objects/reference/durable-objects-migrations.mdx @@ -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. -::: + Use `new_classes` on the migration in your Worker's Wrangler file to create a Durable Object class with the key-value storage backend: @@ -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. diff --git a/src/content/partials/durable-objects/recommend-sqlite-do.mdx b/src/content/partials/durable-objects/recommend-sqlite-do.mdx new file mode 100644 index 00000000000000..6b55486ac85c79 --- /dev/null +++ b/src/content/partials/durable-objects/recommend-sqlite-do.mdx @@ -0,0 +1,11 @@ +--- +{} +--- + +:::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). These Durable Objects can continue to use key-value 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 to SQLite storage for existing Durable Object classes will be available in the future. +::: \ No newline at end of file diff --git a/src/content/partials/durable-objects/storage-intro-text.mdx b/src/content/partials/durable-objects/storage-intro-text.mdx index 7b9d9744dd0391..3f765465ab4fe7 100644 --- a/src/content/partials/durable-objects/storage-intro-text.mdx +++ b/src/content/partials/durable-objects/storage-intro-text.mdx @@ -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. -::: \ No newline at end of file + \ No newline at end of file From 5b4571b24470f00be242805f0a75316d2070f3db Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Tue, 20 May 2025 17:29:50 +0100 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Timo Wilhelm --- src/content/partials/durable-objects/recommend-sqlite-do.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/partials/durable-objects/recommend-sqlite-do.mdx b/src/content/partials/durable-objects/recommend-sqlite-do.mdx index 6b55486ac85c79..af0876f2eda887 100644 --- a/src/content/partials/durable-objects/recommend-sqlite-do.mdx +++ b/src/content/partials/durable-objects/recommend-sqlite-do.mdx @@ -3,9 +3,9 @@ --- :::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). These Durable Objects can continue to use key-value API. +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 key-value 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 to SQLite storage for existing Durable Object classes will be available in the future. +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. ::: \ No newline at end of file From 8cb0569dbe742c1ae800e4a8e15f618d704d904d Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 21 May 2025 09:00:02 +0100 Subject: [PATCH 3/4] Adding link to KV API, applying suggestion --- src/content/partials/durable-objects/recommend-sqlite-do.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/partials/durable-objects/recommend-sqlite-do.mdx b/src/content/partials/durable-objects/recommend-sqlite-do.mdx index 6b55486ac85c79..bc9f913d117348 100644 --- a/src/content/partials/durable-objects/recommend-sqlite-do.mdx +++ b/src/content/partials/durable-objects/recommend-sqlite-do.mdx @@ -3,7 +3,7 @@ --- :::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). These Durable Objects can continue to use key-value API. +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). 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. From 080d640b0e4bbe9d8a6b5f8fdffd0a159c8a4470 Mon Sep 17 00:00:00 2001 From: Jun Lee Date: Wed, 21 May 2025 10:28:15 +0100 Subject: [PATCH 4/4] Implementing feedback --- src/content/partials/durable-objects/recommend-sqlite-do.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/partials/durable-objects/recommend-sqlite-do.mdx b/src/content/partials/durable-objects/recommend-sqlite-do.mdx index af0876f2eda887..b7befa33a91e6d 100644 --- a/src/content/partials/durable-objects/recommend-sqlite-do.mdx +++ b/src/content/partials/durable-objects/recommend-sqlite-do.mdx @@ -3,7 +3,7 @@ --- :::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 key-value API. +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.