From aaa9026d780c88cad0c4e3018c00456027579d16 Mon Sep 17 00:00:00 2001 From: Kenton Varda Date: Tue, 22 Oct 2024 13:25:55 -0500 Subject: [PATCH 1/2] [Durable Objects] Document transaction API changes with SQLite. --- .../docs/durable-objects/api/storage-api.mdx | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/src/content/docs/durable-objects/api/storage-api.mdx b/src/content/docs/durable-objects/api/storage-api.mdx index c87773f37d091c..eb01cdc9b38e4a 100644 --- a/src/content/docs/durable-objects/api/storage-api.mdx +++ b/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.

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.

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)`: + + * 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`: * 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 From 7ebe21fd1ba22d255b4a8d64c1e9f632102ba73b Mon Sep 17 00:00:00 2001 From: Kenton Varda Date: Tue, 22 Oct 2024 14:00:37 -0500 Subject: [PATCH 2/2] [Durable Objects] Fix broken links to SQLite class creation docs. These existing links were just broken. Though, arguably they should actually go to `/durable-objects/best-practices/access-durable-objects-storage/#sqlite-storage-backend`, perhaps? For now I just fixed the links. --- src/content/docs/durable-objects/api/storage-api.mdx | 2 +- src/content/partials/workers/storage_api_pricing.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/docs/durable-objects/api/storage-api.mdx b/src/content/docs/durable-objects/api/storage-api.mdx index eb01cdc9b38e4a..af69c8b20a2461 100644 --- a/src/content/docs/durable-objects/api/storage-api.mdx +++ b/src/content/docs/durable-objects/api/storage-api.mdx @@ -247,7 +247,7 @@ The `put()` method returns a `Promise`, but most applications can discard this p :::note[SQLite in Durable Objects Beta] -SQL API methods accessed with `ctx.storage.sql` are only allowed on [Durable Object classes with SQLite storage backend](/durable-objects/reference/durable-objects-migrations/#enable-sqlite-storage-backend-on-create-durable-object-class-migration) and will return an error if called on Durable Object classes with a key-value storage backend. +SQL API methods accessed with `ctx.storage.sql` are only allowed on [Durable Object classes with SQLite storage backend](/durable-objects/reference/durable-objects-migrations/#enable-sqlite-storage-backend-on-new-durable-object-class-migration) and will return an error if called on Durable Object classes with a key-value storage backend. ::: diff --git a/src/content/partials/workers/storage_api_pricing.mdx b/src/content/partials/workers/storage_api_pricing.mdx index 2707c3d175109a..a570785b5e353f 100644 --- a/src/content/partials/workers/storage_api_pricing.mdx +++ b/src/content/partials/workers/storage_api_pricing.mdx @@ -42,7 +42,7 @@ You can introspect rows read and rows written using `cursor.rowsRead` and `curso ::: -For [Durable Objects classes with SQLite storage backend](/durable-objects/reference/durable-objects-migrations/#enable-sqlite-storage-backend-on-create-durable-object-class-migration) via `ctx.storage.sql` the following pricing is used instead: +For [Durable Objects classes with SQLite storage backend](/durable-objects/reference/durable-objects-migrations/#enable-sqlite-storage-backend-on-new-durable-object-class-migration) via `ctx.storage.sql` the following pricing is used instead: | | Workers Paid plan | | ----------------------------| -------------------------- |