KV-backed Durable Object Storage (Legacy·续

Write buffer behavior

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.

list

  • 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 to list as documented below.

Supported options

  • 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.
  • 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 of start, startKey, or endKey. 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.
  • noCache boolean
  • Same as the option to get(), above.

Alarms

getAlarm

  • 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() returns null.

Supported options

  • Same options as get(), but without noCache.

setAlarm

  • setAlarm(scheduledTime Date | number, options Object optional): Promise
  • Sets the current alarm time, accepting either a JavaScript Date, or integer milliseconds since epoch.

If setAlarm() is called with a time equal to or before Date.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

  • deleteAlarm(options Object optional): Promise
  • Deletes the alarm if one exists. Does not cancel the alarm handler if it is currently executing.

Supported options

  • setAlarm() and deleteAlarm() support the same options as put(), but without noCache.

Other

deleteAll

  • 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 partial deleteAll() issue because deleteAll() operations are atomic (all or nothing).
  • For Workers with a compatibility date of 2026-02-24 or later, deleteAll() also deletes any active alarm. For earlier compatibility dates, deleteAll() does not delete alarms. Use deleteAlarm() separately, or enable the delete_all_deletes_alarm compatibility flag.

transactionSync

  • transactionSync(callback): any
  • Only available when using SQLite-backed Durable Objects.
  • 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(), which complete synchronously.

transaction

  • 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 while await a read operation (unless you use allowConcurrency: 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(), 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, the txn object is obsolete. Any storage operations performed directly on the ctx.storage object, including SQL queries using ctx.storage.sql.exec(), will be considered part of the transaction.

sync

  • 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.

Was this helpful?

YesNo

On this page

KV-backed Durable Object Storage (Legacy·续 - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/durable-objects/api/legacy-kv-storage-api/#page","headline":"KV-backed Durable Object Storage (Legacy)","description":"API reference for the legacy KV-backed Durable Objects storage methods, including get, put, delete, and list.","url":"https://developers.cloudflare.com/durable-objects/api/legacy-kv-storage-api/","inLanguage":"en","image":"https://developers.cloudflare.com/durable-objects/api/legacy-kv-storage-api/og.png?v=0ac53bbc0c561561","dateModified":"2026-04-21","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: API reference for DurableObjectNamespace, which creates IDs and obtains stubs to interact with Durable Objects. title: Durable Object Namespace image: https://developers.cloudflare.com/durable-objects/api/namespace/og.png?v=2d33736d02547d40

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/durable-objects/llms.txt
Use this file to discover all available pages before exploring further.