SQLite in DO clarifications: (cloudflare#17264)

SQLite in DO clarifications:
- deleteAll() behavior
- multi-statement queries with sql.exec

---------

Co-authored-by: Kenton Varda <[email protected]>

Author: vy-ton

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

@@ -100,7 +100,9 @@ Each method is implicitly wrapped inside a transaction, such that its results ar
 
 * <code>deleteAll(options <Type text='Object' /> <MetaInfo text='optional' />)</code>: <Type text='Promise' />
 
-  * Deletes all keys and associated values, effectively deallocating all storage used by the Durable Object. In the event of a failure while the `deleteAll()` operation is still in flight, it may be that only a subset of the data is properly deleted. `deleteAll()` does not proactively delete [Alarms](/durable-objects/api/alarms/). Use [`deleteAlarm()`](/durable-objects/api/alarms/#deletealarm) to delete an alarm.
+  * Deletes all stored data, effectively deallocating all storage used by the Durable Object. For Durable Objects with a key-value storage backend, `deleteAll()` removes all keys and associated values for an individual Durable Object. For Durable Objects with a [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend), `deleteAll()` removes the entire contents of a Durable Object's private SQLite database.  
+  * For Durable Objects with a key-value storage backend, an in-progress `deleteAll()` operation can fail, which may leave a subset of data undeleted. Durable Objects with a SQLite storage backend do not have a partial `deleteAll()` issue because `deleteAll()` operations are atomic (all or nothing).
+  * `deleteAll()` does not proactively delete [Alarms](/durable-objects/api/alarms/). Use [`deleteAlarm()`](/durable-objects/api/alarms/#deletealarm) to delete an alarm.
 
 #### Supported options
 
@@ -245,7 +247,7 @@ SQL API methods accessed with `ctx.storage.sql` are only allowed on [Durable Obj
 
 #### Parameters
 * `query`: <Type text ='string' />
-  * The SQL query string to be executed. `query` can contain `?` placeholders for parameter bindings.
+  * The SQL query string to be executed. `query` can contain `?` placeholders for parameter bindings. Multiple SQL statements, separated with a semicolon, can be executed in the `query`. With multiple SQL statements, any parameter bindings are applied to the last SQL statement in the `query`, and the returned cursor is only for the last SQL statement.
 * `bindings`: <Type text='any[]' /> <MetaInfo text='Optional' />
   * Optional variable number of arguments that correspond to the `?` placeholders in `query`.
 

src/content/docs/durable-objects/best-practices/access-durable-objects-storage.mdx

@@ -42,6 +42,11 @@ export class Counter extends DurableObject {
   }
 }
 ```
+### Removing a Durable Object's 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 alarms), 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