Skip to content

[DO] Updating Durable Objects storage API docs #24964

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 13 commits into from
Sep 24, 2025
Merged

[DO] Updating Durable Objects storage API docs #24964

merged 13 commits into from
Sep 24, 2025

Conversation

@Oxyjun
Copy link
Contributor

@Oxyjun Oxyjun commented Sep 5, 2025 •
edited
Loading

Summary

We're updating the way we present DO Storage API to clearly delineate between the older API for KV-backed DOs, and the newer APIs for SQLite-backed DOs.

  1. Previous "Durable Object Storage" chapter has been split into:
    • "KV-backed Durable Object Storage (Legacy)"; and,
    • "SQLite-backed Durable Object Storage".
  2. Both of the two new chapters start with the same introduction, explaining the differences between the two.
  3. Both pages start with a note component that identifies whether the page is for SQLite-backed DOs or KV-backed DOs.
  4. Repeated text (e.g. Alarms, Other methods, etc) has been put into partial files.
  5. Pending The KV API for SQLite DOs have been modified to reference the new synchronous KV API.
  6. All of the links have been updated to the most logical route. Unless explicitly required, all links will direct to sqlite-storage-api.

Screenshots (optional)

Documentation checklist

  • Is there a changelog entry (guidelines)? If you don't add one for something awesome and new (however small) — how will our customers find out? Changelogs are automatically posted to RSS feeds, the Discord, and X.
  • The documentation style guide has been adhered to.
  • If a larger change - such as adding a new page- an issue has been opened in relation to any incorrect or out of date information that this PR fixes.
  • Files which have changed name or location have been allocated redirects.

@Oxyjun Oxyjun marked this pull request as ready for review September 5, 2025 16:17
@github-actions github-actions bot added size/xl product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. product:durable-objects Durable Objects: https://developers.cloudflare.com/workers/learning/using-durable-objects/ labels Sep 5, 2025
@github-actions
Copy link
Contributor

github-actions bot commented Sep 5, 2025

This PR requires additional review attention because it affects the following areas:

Redirects

This PR changes current filenames or deletes current files. Make sure you have redirects set up to cover the following paths:

  • /durable-objects/api/storage-api/

Partials

This PR updates partial files, which are pieces of content used across multiple files in our Render component.

lambrospetrou
lambrospetrou reviewed Sep 10, 2025
View reviewed changes
lambrospetrou
lambrospetrou reviewed Sep 10, 2025
View reviewed changes
lambrospetrou
lambrospetrou reviewed Sep 10, 2025
View reviewed changes
lambrospetrou
lambrospetrou reviewed Sep 10, 2025
View reviewed changes
Oxyjun
Oxyjun commented Sep 11, 2025
View reviewed changes
lambrospetrou
lambrospetrou reviewed Sep 11, 2025
View reviewed changes
lambrospetrou
lambrospetrou reviewed Sep 11, 2025
View reviewed changes
src/content/partials/durable-objects/api-sync-kv.mdx
- 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 [`Iterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_iterable_protocol) 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](/durable-objects/platform/limits/). If that is a concern, pass options to `list` as documented below.
Copy link
Contributor

@lambrospetrou lambrospetrou Sep 11, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is also not a concern with the Iterable unless the user reads the whole thing and stores it in memory. Not sure if we need to change this, but it's a bit different than the eager array result.

Maybe change it to:

Be aware of how much data may be stored in your Durable Object before calling this version of `list` without options if you will be reading the entire result at once in-memory...

lambrospetrou
lambrospetrou reviewed Sep 11, 2025
View reviewed changes
pedrosousa
pedrosousa approved these changes Sep 11, 2025
View reviewed changes
Oxyjun
Oxyjun commented Sep 11, 2025
View reviewed changes
@Oxyjun Oxyjun assigned Oxyjun and unassigned KianNH Sep 16, 2025
lambrospetrou
lambrospetrou reviewed Sep 17, 2025
View reviewed changes
@Oxyjun Oxyjun merged commit 8f4f101 into production Sep 24, 2025
9 checks passed
@Oxyjun Oxyjun deleted the jun/do/storage-api-docs-revamp branch September 24, 2025 13:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@pedrosousa pedrosousa pedrosousa approved these changes

@lambrospetrou lambrospetrou lambrospetrou approved these changes

@joshthoward joshthoward joshthoward approved these changes

@elithrar elithrar Awaiting requested review from elithrar elithrar is a code owner

@vy-ton vy-ton Awaiting requested review from vy-ton vy-ton is a code owner

@harshil1712 harshil1712 Awaiting requested review from harshil1712 harshil1712 is a code owner

@mikenomitch mikenomitch Awaiting requested review from mikenomitch mikenomitch is a code owner

@irvinebroque irvinebroque Awaiting requested review from irvinebroque irvinebroque is a code owner

@rita3ko rita3ko Awaiting requested review from rita3ko rita3ko is a code owner

@thomasgauvin thomasgauvin Awaiting requested review from thomasgauvin thomasgauvin is a code owner

@threepointone threepointone Awaiting requested review from threepointone threepointone is a code owner

@GregBrimble GregBrimble Awaiting requested review from GregBrimble

@KianNH KianNH Awaiting requested review from KianNH

@WalshyDev WalshyDev Awaiting requested review from WalshyDev

Assignees

@elithrar elithrar

@threepointone threepointone

@pedrosousa pedrosousa

@irvinebroque irvinebroque

@rita3ko rita3ko

@GregBrimble GregBrimble

@WalshyDev WalshyDev

@harshil1712 harshil1712

@thomasgauvin thomasgauvin

@Oxyjun Oxyjun

Labels

product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. product:durable-objects Durable Objects: https://developers.cloudflare.com/workers/learning/using-durable-objects/ size/xl

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.