[Durable Objects] Document transaction API changes with SQLite.

Author: kentonv

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

@@ -191,7 +191,21 @@ The `put()` method returns a `Promise`, but most applications can discard this p
 
 * `txn`
 
-  * Provides access to the `put()`, `get()`, `delete()` and `list()` methods documented above to run in the current transaction context. In order to get transactional behavior within a transaction closure, you must call the methods on the `txn` Object instead of on the top-level `state.storage` Object.<br/><br/>Also supports a `rollback()` function that ensures any changes made during the transaction will be rolled back rather than committed. After `rollback()` is called, any subsequent operations on the `txn` Object will fail with an exception. `rollback()` takes no parameters and returns nothing to the caller.
+  * Provides access to the `put()`, `get()`, `delete()` and `list()` methods documented above to run in the current transaction context. In order to get transactional behavior within a transaction closure, you must call the methods on the `txn` Object instead of on the top-level `ctx.storage` Object.<br/><br/>Also supports a `rollback()` function that ensures any changes made during the transaction will be rolled back rather than committed. After `rollback()` is called, any subsequent operations on the `txn` Object will fail with an exception. `rollback()` takes no parameters and returns nothing to the caller.
+
+  * When using [the SQLite-backed storage engine](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend), the `txn` object is obsolete. Any storage operations performed directly on the `ctx.storage` object, including SQL queries using [`ctx.storage.sql.exec()`](#sqlexec), will be considered part of the transaction.
+
+### transactionSync
+
+* `transactionSync(callback)`: <Type text='any' />
+
+  * Only available when using [the SQLite-backed storage engine](/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend).
+
+  * Invokes `callback()` wrapped in a transaction, and returns its result.
+
+  * If `callback()` throws an exception, the transaction will be rolled back.
+
+  * The callback must complete synchronously, that is, it should not be declared `async` nor otherwise return a Promise. Only synchronous storage operations can be part of the transaction. This is intended for use with SQL queries using [`ctx.storage.sql.exec()`](#sqlexec), which complete sychronously.
 
 ### sync
 
@@ -282,6 +296,8 @@ A cursor (`SqlStorageCursor`) to iterate over query row results as objects. `Sql
 *  `rowsWritten`: <Type text='number' />
   * The number of rows written so far as part of this SQL `query`. This may increase as you iterate the cursor. The final value is used for [SQL billing](/durable-objects/platform/pricing/#sqlite-storage-backend).
 
+Note that `sql.exec()` cannot execute transaction-related statements like `BEGIN TRANSACTION` or `SAVEPOINT`. Instead, use the [`ctx.storage.transaction()`](#transaction) or [`ctx.storage.transactionSync()`](#transactionsync) APIs to start a transaction, and then execute SQL queries in your callback.
+
 #### Examples
 
 <Render file="durable-objects-sql" />