Surfacing SQL storage API ahead of KV storage API

Author: Oxyjun

src/content/docs/durable-objects/api/sql-storage.mdx

@@ -1,5 +1,5 @@
 ---
-title: SQL Storage
+title: SQL storage
 pcx_content_type: concept
 sidebar:
   order: 6
@@ -8,6 +8,21 @@ sidebar:
 
 import { Render, Type, MetaInfo, GlossaryTooltip } from "~/components";
 
+The Durable Object Storage API allows <GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> to access transactional and strongly consistent storage. A Durable Object's attached storage is private to its unique instance and cannot be accessed by other objects.
+
+:::note[Scope of Durable Object storage]
+Note that Durable Object storage is scoped by individual <GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip>.
+
+- An account can have many Durable Object <GlossaryTooltip term="namespace">namespaces</GlossaryTooltip>.
+- A namespace can have many Durable Objects.
+
+However, storage is scoped per individual Durable Object.
+:::
+
+Durable Objects gain access to a persistent Durable Object Storage API via the `DurableObjectStorage` interface and accessed by the `DurableObjectState::storage` property. This is frequently accessed via `this.ctx.storage` when the `ctx` parameter passed to the Durable Object constructor.
+
+JavaScript is a single-threaded and event-driven programming language. This means that JavaScript runtimes, by default, allow requests to interleave with each other which can lead to concurrency bugs. The Durable Objects runtime uses a combination of <GlossaryTooltip term="input gate">input gates</GlossaryTooltip> and <GlossaryTooltip term="output gate">output gates</GlossaryTooltip> to avoid this type of concurrency bug when performing storage operations.
+
 The `SqlStorage` interface encapsulates methods that modify the SQLite database embedded within a Durable Object. The `SqlStorage` interface is accessible via the `sql` property of `DurableObjectStorage` class.
 
 For example, using `sql.exec()`, a user can create a table, then insert rows into the table.
@@ -47,6 +62,8 @@ Specifically for Durable Object classes with SQLite storage backend, KV operatio
 
 ## Methods
 
+<Render file="storage-intro-text"/>
+
 ### `exec`
 
 <code>exec(query: <Type text='string'/>, ...bindings: <Type text='any[]'/>)</code>: <Type text='SqlStorageCursor' />

src/content/docs/durable-objects/api/storage-api.mdx

@@ -1,8 +1,8 @@
 ---
-title: Durable Object Storage
+title: Key-Value storage
 pcx_content_type: concept
 sidebar:
-  order: 6
+  order: 7
 ---
 
 import {
@@ -13,21 +13,6 @@ import {
 	TypeScriptExample,
 } from "~/components";
 
-The Durable Object Storage API allows <GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip> to access transactional and strongly consistent storage. A Durable Object's attached storage is private to its unique instance and cannot be accessed by other objects.
-
-:::note[Scope of Durable Object storage]
-Note that Durable Object storage is scoped by individual <GlossaryTooltip term="Durable Object">Durable Objects</GlossaryTooltip>.
-
-- An account can have many Durable Object <GlossaryTooltip term="namespace">namespaces</GlossaryTooltip>.
-- A namespace can have many Durable Objects.
-
-However, storage is scoped per individual Durable Object.
-:::
-
-Durable Objects gain access to a persistent Durable Object Storage API via the `DurableObjectStorage` interface and accessed by the `DurableObjectState::storage` property. This is frequently accessed via `this.ctx.storage` when the `ctx` parameter passed to the Durable Object constructor.
-
-JavaScript is a single-threaded and event-driven programming language. This means that JavaScript runtimes, by default, allow requests to interleave with each other which can lead to concurrency bugs. The Durable Objects runtime uses a combination of <GlossaryTooltip term="input gate">input gates</GlossaryTooltip> and <GlossaryTooltip term="output gate">output gates</GlossaryTooltip> to avoid this type of concurrency bug when performing storage operations.
-
 The following code snippet shows you how to store and retrieve data using the Durable Object Storage API.
 
 <TypeScriptExample>
@@ -51,17 +36,7 @@ export class Counter extends DurableObject {
 
 ## Methods
 
-:::note[SQLite in Durable Objects]
-SQLite-backed Durable Objects can have a private, embedded SQLite database. When deploying a new Durable Object class, users can [use a SQLite storage backend](/durable-objects/features/access-sqlite-storage/#sqlite-storage-backend) to access the [SQL API](/durable-objects/api/sql-storage/#exec).
-
-:::
-
-The Durable Object Storage API comes with several methods, including key-value (KV) API, SQL API, and point-in-time-recovery (PITR) API.
-
-- Durable Object classes with the default, key-value storage backend can use KV API.
-- Durable Object classes with the [SQLite storage backend](/durable-objects/features/access-sqlite-storage/#sqlite-storage-backend) can use KV API, SQL API, and PITR API. KV API methods like `get()`, `put()`, `delete()`, or `list()` store data in a hidden SQLite table.
-
-Each method is implicitly wrapped inside a transaction, such that its results are atomic and isolated from all other storage operations, even when accessing multiple key-value pairs.
+<Render file="storage-intro-text"/>
 
 ### `get`
 

src/content/docs/durable-objects/features/access-sqlite-storage.mdx

@@ -16,7 +16,7 @@ A Durable Object's [in-memory state](/durable-objects/reference/in-memory-state/
 
 By default, a <GlossaryTooltip term="Durable Object class">Durable Object class</GlossaryTooltip> leverages a SQLite storage backend.
 
-[Storage API methods](/durable-objects/api/storage-api/#methods) are available on `ctx.storage` parameter passed to the Durable Object constructor. Storage API has key-value APIs and SQL APIs. Only Durable Object classes with a SQLite storage backend can access SQL API.
+[Storage API methods](/durable-objects/api/storage-api/#methods) are available on `ctx.storage` parameter passed to the Durable Object constructor. Storage API has SQL APIs and key-value APIs. Only Durable Object classes with a SQLite storage backend can access SQL API.
 
 A common pattern is to initialize a Durable Object from [persistent storage](/durable-objects/api/storage-api/) and set instance variables the first time it is accessed. Since future accesses are routed to the same Durable Object, it is then possible to return any initialized values without making further calls to persistent storage.
 
@@ -42,17 +42,15 @@ export class Counter extends DurableObject {
   }
 }
 ```
-### Removing a Durable Object's storage
+## Remove storage
 
 A Durable Object fully ceases to exist if, when it shuts down, its storage is empty. If you never write to a Durable Object's storage at all (including setting <GlossaryTooltip term="alarm">alarms</GlossaryTooltip>), then storage remains empty, and so the Durable Object will no longer exist once it shuts down.
 
 However if you ever write using [Storage API](/durable-objects/api/storage-api/), including setting alarms, then you must explicitly call [`storage.deleteAll()`](/durable-objects/api/storage-api/#deleteall) to empty storage. It is not sufficient to simply delete the specific data that you wrote, such as deleting a key or dropping a table, as some metadata may remain. The only way to remove all storage is to call `deleteAll()`. Calling `deleteAll()` ensures that a Durable Object will not be billed for storage.
 
-## SQLite storage backend
+## Wrangler configuration for SQLite Durable Objects
 
-By default, Durable Objects use SQLite storage backend.
-
-To allow a new Durable Object class to use SQLite storage backend, use `new_sqlite_classes` on the migration in your Worker's Wrangler file:
+By default, Durable Objects use SQLite storage backend. This means the Wrangler file uses `new_sqlite_classes` on the migration, by default:
 
 <WranglerConfig>
 
@@ -66,7 +64,7 @@ new_sqlite_classes = ["MyDurableObject"] # Array of new classes
 
 [SQL API](/durable-objects/api/sql-storage/#exec) is available on `ctx.storage.sql` parameter passed to the Durable Object constructor.
 
-### Examples
+## Examples
 
 <Render file="durable-objects-sql" />
 

src/content/docs/durable-objects/index.mdx

@@ -16,7 +16,7 @@ import { Render, CardGrid, Description, Feature, LinkTitleCard, Plan, RelatedPro
 Create collaborative applications, real-time chat, multiplayer games and more without needing to coordinate state or manage infrastructure.
 </Description>
 
-<Plan type="paid" />
+<Plan type="workers-all" />
 
 Durable Objects provide a building block for stateful applications and distributed systems.
 

src/content/docs/durable-objects/reference/durable-objects-migrations.mdx

@@ -270,20 +270,5 @@ new_classes = ["DurableObjectExample"] # Array of new classes
 
 You can rename the `DurableObjectExample` class to `UpdatedName` and delete an outdated `DeprecatedClass` entirely. You can create separate migrations for each operation, or combine them into a single migration as shown below. */}
 
-## Enable SQLite storage backend on new Durable Object class migration
 
-To allow a new Durable Object class to use a SQLite storage backend, use `new_sqlite_classes` on the migration in your Worker's `wrangler` configuration file:
-
-<WranglerConfig>
-
-```toml
-[[migrations]]
-tag = "v1" # Should be unique for each entry
-new_sqlite_classes = ["MyDurableObject"] # Array of new classes
-```
-
-</WranglerConfig>
-
-:::caution
 You cannot enable a SQLite storage backend on an existing, deployed Durable Object class, so setting `new_sqlite_classes` on later migrations will fail with an error. Automatic migration of deployed classes from their key-value storage backend to SQLite storage backend will be available in the future.
-:::

src/content/docs/workers/platform/pricing.mdx

@@ -11,7 +11,7 @@ import { GlossaryTooltip, Render } from "~/components";
 
 By default, users have access to the Workers Free plan.
 
-The Workers Free plan includes limited usage of Workers, Pages Functions and Workers KV. The daily free limit resets at 00:00 UTC. When the daily limit is reached, further operations of that type will fail with an error, until the limits reset again. For more information on the Free plan, refer to [Free plan limits](/workers/platform/limits/#worker-limits).
+The Workers Free plan includes limited usage of Workers and other products. Daily free limits for these products reset at 00:00 UTC. When the daily limit is reached, further operations of that type will fail with an error, until the limits reset again. For more information on the Free plan, refer to [Free plan limits](/workers/platform/limits/#worker-limits).
 
 The Workers Paid plan includes Workers, Pages Functions, Workers KV, and Durable Objects usage for a minimum charge of $5 USD per month for an account. The plan includes increased initial usage allotments, with clear charges for usage that exceeds the base plan.
 

src/content/partials/durable-objects/storage-intro-text.mdx

@@ -0,0 +1,10 @@
+---
+{}
+---
+
+The Durable Object Storage API comes with several methods, including key-value (KV) API, SQL API, and point-in-time-recovery (PITR) API.
+
+- Durable Object classes with the default, [SQLite storage backend](/durable-objects/features/access-sqlite-storage/#sqlite-storage-backend) can use KV API, SQL API, and PITR API. KV API methods like `get()`, `put()`, `delete()`, or `list()` store data in a hidden SQLite table.
+- Durable Object classes with the key-value storage backend can use KV API.
+
+Each method is implicitly wrapped inside a transaction, such that its results are atomic and isolated from all other storage operations, even when accessing multiple key-value pairs.