DO SQLite Notes

Store and retrieve per-user notes in SQLite-backed Durable Objects. Each userId maps to its own Durable Object stub; notes live in a notes table via storage.sql.exec.

API ReferenceCopy Anchor Link

POST /notesCopy Anchor Link

Create or update a note for a user.

userId string (required)

User identifier (letters, numbers, _, -).

id string (required)

Note identifier (letters, numbers, _, -).

content string (required)

Note body (max 4,000 characters).

Example RequestCopy Anchor Link

curl -X POST "https://your-worker.workers.dev/notes" \
  -H "Content-Type: application/json" \
  -d '{"userId":"alice","id":"n1","content":"Hello"}'

Success ResponseCopy Anchor Link

{
  "userId": "alice",
  "id": "n1",
  "content": "Hello",
  "updatedAt": "2025-06-20T12:00:00.000Z"
}

GET /notesCopy Anchor Link

Fetch one note (?userId=&id=) or list all notes for a user (?userId=).

userId string (required)

id string (optional)

When present, returns a single note; otherwise returns { userId, notes }.

Example RequestCopy Anchor Link

curl "https://your-worker.workers.dev/notes?userId=alice"
curl "https://your-worker.workers.dev/notes?userId=alice&id=n1"

DELETE /notesCopy Anchor Link

Delete a note by user and id.

userId string (required)

id string (required)

Example RequestCopy Anchor Link

curl -X DELETE "https://your-worker.workers.dev/notes?userId=alice&id=n1"

Error CodesCopy Anchor Link

• 400 - Invalid userId, id, content, or body (INVALID_USER_ID, INVALID_ID, INVALID_CONTENT, INVALID_BODY)
• 404 - Note not found (NOT_FOUND)

Use CasesCopy Anchor Link

• Learn SQLite storage inside Durable Objects (new_sqlite_classes)
• Per-tenant or per-user isolated state without a shared D1 database
• Prototype note or config APIs with strong consistency per user
• Compare DO SQLite vs Workers KV for structured records

LimitationsCopy Anchor Link

• Note IDs and userIds are capped to alphanumeric plus _ / -
• Content max 4,000 characters
• No authentication; any client can read or write by userId
• Requires a Durable Objects binding and SQLite migration

DeploymentCopy Anchor Link

curl -X POST "https://your-worker.workers.dev/notes" \
  -H "Content-Type: application/json" \
  -d '{"userId":"alice","id":"n1","content":"Hello"}'

Local DevelopmentCopy Anchor Link

cd apps/experiments/do-sqlite-notes
npm install
npm run dev

curl -X POST "http://localhost:8787/notes" \
  -H "Content-Type: application/json" \
  -d '{"userId":"alice","id":"n1","content":"Hello"}'

ConfigurationCopy Anchor Link

wrangler.json declares:

• Durable Object binding NOTES → class NotesDO
• Migration v1 with new_sqlite_classes: ["NotesDO"]

Cloudflare Features UsedCopy Anchor Link

• Workers - Edge compute runtime
• Durable Objects - Per-user stub with SQLite storage
• SQLite in Durable Objects - storage.sql.exec for the notes table