You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: src/content/docs/durable-objects/api/storage-api.mdx
+17-17Lines changed: 17 additions & 17 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -8,7 +8,7 @@ sidebar:
8
8
9
9
import { Render } from"~/components";
10
10
11
-
The Storage API allows Durable Objects 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.
11
+
The Storage API allows Durable Objects 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.
12
12
13
13
Durable Objects gain access to a persistent Storage API via `ctx.storage`, on the `ctx` parameter passed to the Durable Object constructor.
14
14
@@ -26,13 +26,13 @@ export class Counter {
26
26
let url =newURL(request.url);
27
27
28
28
// retrieve data
29
-
let value = (awaitthis.ctx.storage.get("value")) ||0;
29
+
let value = (awaitthis.ctx.storage.get("value")) ||0;
30
30
31
31
// increment counter and get a new value
32
-
value +=1;
32
+
value +=1;
33
33
34
34
// store data
35
-
awaitthis.ctx.storage.put("value", value);
35
+
awaitthis.ctx.storage.put("value", value);
36
36
37
37
returnnewResponse(value);
38
38
}
@@ -47,10 +47,10 @@ The ew beta version of Durable Objects is available where each Durable Object ha
47
47
48
48
:::
49
49
50
-
The Storage API comes with several methods, including key-value (KV) API, SQL API, and point-in-time-recovery (PITR) API.
50
+
The Storage API comes with several methods, including key-value (KV) API, SQL API, and point-in-time-recovery (PITR) API.
51
51
52
52
- Durable Object classes with the default, key-value storage backend can use KV API.
53
-
- Durable Object classes with the [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-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.
53
+
- Durable Object classes with the [SQLite storage backend](/durable-objects/best-practices/access-durable-objects-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.
54
54
55
55
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.
56
56
@@ -126,12 +126,12 @@ Each method is implicitly wrapped inside a transaction, such that its results ar
126
126
127
127
:::note[Automatic write coalescing]
128
128
129
-
If you invoke `put()` (or `delete()`) multiple times without performing any `await` in the meantime, the operations will automatically be combined and submitted atomically. In case of a machine failure, either all of the writes will have been stored to disk or none of the writes will have been stored to disk.
129
+
If you invoke `put()` (or `delete()`) multiple times without performing any `await` in the meantime, the operations will automatically be combined and submitted atomically. In case of a machine failure, either all of the writes will have been stored to disk or none of the writes will have been stored to disk.
130
130
:::
131
131
132
132
:::note[Write buffer behavior]
133
133
134
-
The `put()` method returns a `Promise`, but most applications can discard this promise without using `await`. The `Promise` usually completes immediately, because `put()` writes to an in-memory write buffer that is flushed to disk asynchronously. However, if an application performs a large number of `put()` without waiting for any I/O, the write buffer could theoretically grow large enough to cause the isolate to exceed its 128 MB memory limit. To avoid this scenario, such applications should use `await` on the `Promise` returned by `put()`. The system will then apply backpressure onto the application, slowing it down so that the write buffer has time to flush. Using `await` will disable automatic write coalescing.
134
+
The `put()` method returns a `Promise`, but most applications can discard this promise without using `await`. The `Promise` usually completes immediately, because `put()` writes to an in-memory write buffer that is flushed to disk asynchronously. However, if an application performs a large number of `put()` without waiting for any I/O, the write buffer could theoretically grow large enough to cause the isolate to exceed its 128 MB memory limit. To avoid this scenario, such applications should use `await` on the `Promise` returned by `put()`. The system will then apply backpressure onto the application, slowing it down so that the write buffer has time to flush. Using `await` will disable automatic write coalescing.
135
135
:::
136
136
137
137
### list
@@ -231,31 +231,31 @@ The `put()` method returns a `Promise`, but most applications can discard this p
231
231
232
232
:::note[SQLite in Durable Objects Beta]
233
233
234
-
SQL API methods accessed with `ctx.storage.sql` are only allowed on [Durable Object classes with SQLite storage backen](/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.
234
+
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.
* The SQL query string to be executed. `query` can contain `?` placeholders for parameter bindings.
243
243
*`bindings`: any[] Optional
244
244
* Optional variable number of arguments that correspond to the `?` placeholders in `query`.
245
245
246
-
#### Returns
246
+
#### Returns
247
247
A cursor (`SqlStorageCursor`) to iterate over query row results as objects. `SqlStorageCursor` is a JavaScript [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol), which supports iteration using `for (let row of cursor)`. `SqlStorageCursor` is also a JavaScript [Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol), which supports iteration using `cursor.next()`.
248
248
249
249
`SqlStorageCursor` supports the following methods:
250
-
250
+
251
251
*`next()`
252
-
* Returns an object representing the next value of the cursor. The returned object has `done` and `value` properties adhering to the JavaScript [Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol). `done` is set to `false` when a next value is present, and `value` is set to the next row object in the query result. `done` is set to `true` when the entire cursor is consumed, and no `value` is set.
252
+
* Returns an object representing the next value of the cursor. The returned object has `done` and `value` properties adhering to the JavaScript [Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterator_protocol). `done` is set to `false` when a next value is present, and `value` is set to the next row object in the query result. `done` is set to `true` when the entire cursor is consumed, and no `value` is set.
253
253
*`toArray()`
254
-
* Iterates through remaining cursor value(s) and returns an array of returned row objects.
254
+
* Iterates through remaining cursor value(s) and returns an array of returned row objects.
255
255
*`one()`
256
-
* Returns a row object if query result has exactly one row. If query result has zero rows or more than one row, `one()` throws an exception.
256
+
* Returns a row object if query result has exactly one row. If query result has zero rows or more than one row, `one()` throws an exception.
257
257
*`raw()`: Iterator
258
-
* Returns an Iterator over the same query results, with each row as an array of column values (with no column names) rather than an object.
258
+
* Returns an Iterator over the same query results, with each row as an array of column values (with no column names) rather than an object.
259
259
* Returned Iterator supports `next()`, `toArray()`, and `one()` methods above.
260
260
* Returned cursor and `raw()` iterator iterate over the same query results and can be combined. For example:
261
261
@@ -297,7 +297,7 @@ The current SQLite database size in bytes.
297
297
298
298
### Point in time recovery
299
299
300
-
For [Durable Objects classes with SQL storage](/durable-objects/reference/durable-objects-migrations/#enable-sqlite-storage-backend-on-new-durable-object-class-migration), the following point-in-time-recovery (PITR) API methods are available to restore a Durable Object's embedded SQLite database to any point in time in the past 30 days. These methods apply to the entire SQLite database contents, including both the object's stored SQL data and stored key-value data using the key-value `put()` API. The PITR API is not supported in local development because a durable log of data changes is not stored locally.
300
+
For [Durable Objects classes with SQL storage](/durable-objects/reference/durable-objects-migrations/#enable-sqlite-storage-backend-on-new-durable-object-class-migration), the following point-in-time-recovery (PITR) API methods are available to restore a Durable Object's embedded SQLite database to any point in time in the past 30 days. These methods apply to the entire SQLite database contents, including both the object's stored SQL data and stored key-value data using the key-value `put()` API. The PITR API is not supported in local development because a durable log of data changes is not stored locally.
301
301
302
302
The PITR API represents points in times using "bookmarks". A bookmark is a mostly alphanumeric string like `0000007b-0000b26e-00001538-0c3e87bb37b3db5cc52eedb93cd3b96b`. Bookmarks are designed to be lexically comparable: a bookmark representing an earlier point in time compares less than one representing a later point, using regular string comparison.
0 commit comments