Skip to content

Conversation

mmkal
Copy link

@mmkal mmkal commented Sep 24, 2025

Summary

fixes #25018

copying summary from there:

Existing documentation URL(s)

https://developers.cloudflare.com/agents/api-reference/store-and-sync-state/#sql-api

The first example of the this.sql helper uses await which is functional but misleading that it's necessary(?) and doesn't showcase the value:

export class MyAgent extends Agent<Env> {
  async onRequest(request: Request) {
    let userId = new URL(request.url).searchParams.get('userId');

    // 'users' is just an example here: you can create arbitrary tables and define your own schemas
    // within each Agent's database using SQL (SQLite syntax).
    let user = await this.sql`SELECT * FROM users WHERE id = ${userId}`
    return Response.json(user)
  }
}

I think it's also probably misleading to imply the return value from that particular sql query is user given this.sql returns an array? Have I got this wrong?

What changes are you suggesting?

An sync/singular example like

let [user] = this.sql`select * from users where id = ${userId}`

Additional information

Intro blog mentions it's synchronous! https://blog.cloudflare.com/sqlite-in-durable-objects/#reads-and-writes-are-synchronous

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
product:agents Build and deploy AI-powered Agents on Cloudflare that can act autonomously. September 2025 size/xs
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Durable objects SQL API docs use await unnecessarily
6 participants