Storage API
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.
Durable Objects gain access to a persistent Storage API via ctx.storage
, on the ctx
parameter passed to the Durable Object constructor.
While access to a Durable Object instance is single-threaded, request executions can still interleave with each other when they wait on I/O, such as when waiting on the promises returned by persistent storage methods or fetch()
requests.
The following code snippet shows you how to store and retrieve data using the Storage API.
The 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 can use KV API, SQL API, and PITR API. KV API methods like
get()
,put()
,delete()
, orlist()
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.
-
get(key string , options Object optional)
: Promise<any>- Retrieves the value associated with the given key. The type of the returned value will be whatever was previously written for the key, or undefined if the key does not exist.
-
get(keys Array<string> , options Object optional)
: Promise<Map<string, any>>- Retrieves the values associated with each of the provided keys. The type of each returned value in the
Map
↗ will be whatever was previously written for the corresponding key. Results in theMap
will be sorted in increasing order of their UTF-8 encodings, with any requested keys that do not exist being omitted. Supports up to 128 keys at a time.
- Retrieves the values associated with each of the provided keys. The type of each returned value in the
-
allowConcurrency
: boolean- By default, the system will pause delivery of I/O events to the Object while a storage operation is in progress, in order to avoid unexpected race conditions. Pass
allowConcurrency: true
to opt out of this behavior and allow concurrent events to be delivered.
- By default, the system will pause delivery of I/O events to the Object while a storage operation is in progress, in order to avoid unexpected race conditions. Pass
-
noCache
: boolean- If true, then the key/value will not be inserted into the in-memory cache. If the key is already in the cache, the cached value will be returned, but its last-used time will not be updated. Use this when you expect this key will not be used again in the near future. This flag is only a hint. This flag will never change the semantics of your code, but it may affect performance.
-
put(key string , value any , options Object optional)
: Promise- Stores the value and associates it with the given key. The value can be any type supported by the structured clone algorithm ↗, which is true of most types. Keys are limited to a max size of 2,048 bytes and values are limited to 128 KiB (131,072 bytes).
- Stores the value and associates it with the given key. The value can be any type supported by the structured clone algorithm ↗, which is true of most types. Keys are limited to a max size of 2,048 bytes and values are limited to 128 KiB (131,072 bytes).
-
put(entries Object , options Object optional)
: Promise- Takes an Object and stores each of its keys and values to storage.
- Each value can be any type supported by the structured clone algorithm ↗, which is true of most types.
- Supports up to 128 key-value pairs at a time. Each key is limited to a maximum size of 2,048 bytes and each value is limited to 128 KiB (131,072 bytes).
-
delete(key string , options Object optional)
: Promise<boolean>- Deletes the key and associated value. Returns
true
if the key existed orfalse
if it did not.
- Deletes the key and associated value. Returns
-
delete(keys Array<string> , options Object optional)
: Promise<number>- Deletes the provided keys and their associated values. Supports up to 128 keys at a time. Returns a count of the number of key-value pairs deleted.
-
deleteAll(options Object optional)
: Promise- 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,deleteAll()
removes the entire contents of a Durable Object’s private SQLite database, including both SQL data and key-value data. - 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 partialdeleteAll()
issue becausedeleteAll()
operations are atomic (all or nothing). deleteAll()
does not proactively delete Alarms. UsedeleteAlarm()
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,
-
put()
,delete()
anddeleteAll()
support the following options: -
allowUnconfirmed
boolean-
By default, the system will pause outgoing network messages from the Durable Object until all previous writes have been confirmed flushed to disk. If the write fails, the system will reset the Object, discard all outgoing messages, and respond to any clients with errors instead.
-
This way, Durable Objects can continue executing in parallel with a write operation, without having to worry about prematurely confirming writes, because it is impossible for any external party to observe the Object’s actions unless the write actually succeeds.
-
After any write, subsequent network messages may be slightly delayed. Some applications may consider it acceptable to communicate on the basis of unconfirmed writes. Some programs may prefer to allow network traffic immediately. In this case, set
allowUnconfirmed
totrue
to opt out of the default behavior. -
If you want to allow some outgoing network messages to proceed immediately but not others, you can use the allowUnconfirmed option to avoid blocking the messages that you want to proceed and then separately call the
sync()
method, which returns a promise that only resolves once all previous writes have successfully been persisted to disk.
-
-
noCache
boolean-
If true, then the key/value will be discarded from memory as soon as it has completed writing to disk.
-
Use
noCache
if the key will not be used again in the near future.noCache
will never change the semantics of your code, but it may affect performance. -
If you use
get()
to retrieve the key before the write has completed, the copy from the write buffer will be returned, thus ensuring consistency with the latest call toput()
.
-
-
list(options Object optional)
: Promise<Map<string, any>>-
Returns all keys and values associated with the current Durable Object in ascending sorted order based on the keys’ UTF-8 encodings.
-
The type of each returned value in the
Map
↗ will be whatever was previously written for the corresponding key. -
Be aware of how much data may be stored in your Durable Object before calling this version of
list
without options because all the data will be loaded into the Durable Object’s memory, potentially hitting its limit. If that is a concern, pass options tolist
as documented below.
-
-
start
string- Key at which the list results should start, inclusive.
-
startAfter
string- Key after which the list results should start, exclusive. Cannot be used simultaneously with
start
.
- Key after which the list results should start, exclusive. Cannot be used simultaneously with
-
end
string- Key at which the list results should end, exclusive.
-
prefix
string- Restricts results to only include key-value pairs whose keys begin with the prefix.
-
reverse
boolean- If true, return results in descending order instead of the default ascending order.
- Enabling
reverse
does not change the meaning ofstart
,startKey
, orendKey
.start
still defines the smallest key in lexicographic order that can be returned (inclusive), effectively serving as the endpoint for a reverse-order list.end
still defines the largest key in lexicographic order that the list should consider (exclusive), effectively serving as the starting point for a reverse-order list.
-
limit
number- Maximum number of key-value pairs to return.
-
allowConcurrency
boolean- Same as the option to
get()
, above.
- Same as the option to
-
noCache
boolean- Same as the option to
get()
, above.
- Same as the option to
-
transaction(closureFunction(txn))
: Promise-
Runs the sequence of storage operations called on
txn
in a single transaction that either commits successfully or aborts. -
Explicit transactions are no longer necessary. Any series of write operations with no intervening
await
will automatically be submitted atomically, and the system will prevent concurrent events from executing whileawait
a read operation (unless you useallowConcurrency: true
). Therefore, a series of reads followed by a series of writes (with no other intervening I/O) are automatically atomic and behave like a transaction.
-
-
txn
- Provides access to the
put()
,get()
,delete()
andlist()
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 thetxn
Object instead of on the top-levelstate.storage
Object.
Also supports arollback()
function that ensures any changes made during the transaction will be rolled back rather than committed. Afterrollback()
is called, any subsequent operations on thetxn
Object will fail with an exception.rollback()
takes no parameters and returns nothing to the caller.
- Provides access to the
-
sync()
: Promise-
Synchronizes any pending writes to disk.
-
This is similar to normal behavior from automatic write coalescing. If there are any pending writes in the write buffer (including those submitted with the
allowUnconfirmed
option), the returned promise will resolve when they complete. If there are no pending writes, the returned promise will be already resolved.
-
-
getAlarm(options Object optional)
: Promise<Number | null>- Retrieves the current alarm time (if set) as integer milliseconds since epoch. The alarm is considered to be set if it has not started, or if it has failed and any retry has not begun. If no alarm is set,
getAlarm()
returnsnull
.
- Retrieves the current alarm time (if set) as integer milliseconds since epoch. The alarm is considered to be set if it has not started, or if it has failed and any retry has not begun. If no alarm is set,
- Same options as
get()
, but withoutnoCache
.
-
setAlarm(scheduledTime Date | number , options Object optional)
: Promise-
Sets the current alarm time, accepting either a JavaScript
Date
, or integer milliseconds since epoch.
IfsetAlarm()
is called with a time equal to or beforeDate.now()
, the alarm will be scheduled for asynchronous execution in the immediate future. If the alarm handler is currently executing in this case, it will not be canceled. Alarms can be set to millisecond granularity and will usually execute within a few milliseconds after the set time, but can be delayed by up to a minute due to maintenance or failures while failover takes place.
-
-
deleteAlarm(options Object optional)
: Promise- Deletes the alarm if one exists. Does not cancel the alarm handler if it is currently executing.
setAlarm()
anddeleteAlarm()
support the same options asput()
, but withoutnoCache
.
ctx.storage.sql.exec(query: string , …bindings: any[] )
: SqlStorageCursor
query
: string- 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 thequery
. With multiple SQL statements, any parameter bindings are applied to the last SQL statement in thequery
, and the returned cursor is only for the last SQL statement.
- The SQL query string to be executed.
bindings
: any[] Optional- Optional variable number of arguments that correspond to the
?
placeholders inquery
.
- Optional variable number of arguments that correspond to the
A cursor (SqlStorageCursor
) to iterate over query row results as objects. SqlStorageCursor
is a JavaScript Iterable ↗, which supports iteration using for (let row of cursor)
. SqlStorageCursor
is also a JavaScript Iterator ↗, which supports iteration using cursor.next()
.
SqlStorageCursor
supports the following methods:
next()
- Returns an object representing the next value of the cursor. The returned object has
done
andvalue
properties adhering to the JavaScript Iterator ↗.done
is set tofalse
when a next value is present, andvalue
is set to the next row object in the query result.done
is set totrue
when the entire cursor is consumed, and novalue
is set.
- Returns an object representing the next value of the cursor. The returned object has
toArray()
- Iterates through remaining cursor value(s) and returns an array of returned row objects.
one()
- 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.
- Returns a row object if query result has exactly one row. If query result has zero rows or more than one row,
raw()
: Iterator- 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.
- Returned Iterator supports
next()
,toArray()
, andone()
methods above. - Returned cursor and
raw()
iterator iterate over the same query results and can be combined. For example:
SqlStorageCursor
had the following properties:
columnNames
: string[]- The column names of the query in the order they appear in each row array returned by the
raw
iterator.
- The column names of the query in the order they appear in each row array returned by the
rowsRead
: number- The number of rows read so far as part of this SQL
query
. This may increase as you iterate the cursor. The final value is used for SQL billing. rowsWritten
: 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.
SQL API examples below use the following SQL schema:
Iterate over query results as row objects:
Convert query results to an array of row objects:
Convert query results to an array of row values arrays:
Get first row object of query results:
Check if query results have exactly one row:
Returned cursor behavior:
Returned cursor and raw()
iterator iterate over the same query results:
sql.exec().rowsRead()
:
ctx.storage.sql.databaseSize
: number
The current SQLite database size in bytes.
For Durable Objects classes with SQL storage, 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.
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.
ctx.storage.getCurrentBookmark()
: Promise<string>
- Returns a bookmark representing the current point in time in the object’s history.
ctx.storage.getBookmarkForTime(timestamp: number | Date )
: Promise<string>
- Returns a bookmark representing approximately the given point in time, which must be within the last 30 days. If the timestamp is represented as a number, it is converted to a date as if using
new Date(timestamp)
.
ctx.storage.onNextSessionRestoreBookmark(bookmark: string )
: Promise<string>
- Configure the Durable Object so that the next time it restarts, it should restore its storage to exactly match what the storage contained at the given bookmark. After calling this, the application should typically invoke
ctx.abort()
to restart the Durable Object, thus completing the point-in-time recovery.
This method returns a special bookmark representing the point in time immediately before the recovery takes place (even though that point in time is still technically in the future). Thus, after the recovery completes, it can be undone by performing a second recovery to this bookmark.