EdgeOne Makers Storage
🗄️ There is NO managed database on this platform — no SQL, no MongoDB, no Prisma, no ORM. Do not reach for sqlite, pg, mysql, mongodb, or an in-memory array (it resets on every cold start / redeploy). Blob IS your database. Any dynamic data a generated site needs to persist — guestbook messages, uploaded drawings, votes, leaderboards, per-user save state, form submissions — is modeled as Blob keys. Model your "tables" as key prefixes (messages/<id>.json, users/<uid>.json). See references/blob.md → "Blob as your backend".
⚠️ Local dev does NOT always require login. edgeone makers dev runs without authentication for pure-static previews. Login only becomes necessary through this chain: using Blob ⇒ the project must be linked ⇒ linking requires a logged-in account first. So if (and only if) dev/deploy must read/write Blob (or any credentialed backend), run edgeone login (browser) or pass -t <token> before linking/starting dev. If your site has no backend, skip login and just run edgeone makers dev. See also makers-env-adaption (Login authentication + Project linking).
⛔ When the project uses Blob/KV, ALWAYS pass -n <project-name> to edgeone makers dev. Bare edgeone makers dev drops into an interactive "Link existing / Create and link" picker that hangs in sandbox / non-interactive environments. With -n, the CLI auto-creates the project if the name doesn't exist yet — one command, no separate step needed.
🔒 Every Blob store: getStore({ name, consistency: "strong" }) — never the string form getStore("name"). The string form defaults to eventual consistency and causes "I just wrote but the next read returns stale/null" bugs. Full rule and rationale: references/blob.md → IRON RULE (top of file).
EdgeOne Makers provides two storage services. Choose based on your runtime and data type:
| Storage |
Runtime |
Data Type |
SDK |
Use Case |
| KV |
Edge Functions only |
Small key-value pairs (≤ 25 MB) |
Global variable (no npm) |
Counters, config, session tokens, simple CRUD |
| Blob |
Cloud Functions (Makers Functions) |
Files & objects (images, docs, uploads) |
@edgeone/pages-blob (npm) |
User uploads, AI-generated content, file management |
Decision Tree
Need to persist anything (records, lists, counters, uploads, save state)?
├─ Edge Function (V8 runtime, no npm)?
│ → KV Storage (global variable) → read references/kv.md
└─ Cloud Function (Node.js, has npm)? ← default for any real backend
├─ Files / images / large objects?
│ → Blob Storage → read references/blob.md
└─ Structured data (records, lists, counters, per-user state)?
→ Blob with setJSON / key prefixes → read references/blob.md
Routing
| Task |
Read |
| KV Storage (Edge Functions, global variable, put/get/delete/list) |
references/kv.md |
| Blob Storage (Cloud Functions, npm SDK, file upload/download, pre-signed URLs) |
references/blob.md |
1---2name: edgeone-makers-storage3description: KV and Blob storage services on EdgeOne Makers. KV for edge key-value pairs, Blob for file/object storage in Cloud Functions. Covers SDK usage, setup, and troubleshooting.4---5
6# EdgeOne Makers Storage
7
8> 🗄️ **There is NO managed database on this platform** — no SQL, no MongoDB, no Prisma, no ORM. Do **not** reach for `sqlite`, `pg`, `mysql`, `mongodb`, or an in-memory array (it resets on every cold start / redeploy). **Blob IS your database.** Any dynamic data a generated site needs to persist — guestbook messages, uploaded drawings, votes, leaderboards, per-user save state, form submissions — is modeled as Blob keys. Model your "tables" as **key prefixes** (`messages/<id>.json`, `users/<uid>.json`). See [references/blob.md](references/blob.md) → "Blob as your backend".
9
10> ⚠️ **Local dev does NOT always require login.** `edgeone makers dev` runs without authentication for **pure-static** previews. Login only becomes necessary through this chain: **using Blob ⇒ the project must be `link`ed ⇒ linking requires a logged-in account first.** So if (and only if) dev/deploy must read/write **Blob** (or any credentialed backend), run `edgeone login` (browser) or pass `-t <token>` before linking/starting dev. **If your site has no backend, skip login and just run `edgeone makers dev`.** See also makers-env-adaption (Login authentication + Project linking).
11>
12> ⛔ **When the project uses Blob/KV, ALWAYS pass `-n <project-name>` to `edgeone makers dev`.** Bare `edgeone makers dev` drops into an interactive "Link existing / Create and link" picker that hangs in sandbox / non-interactive environments. With `-n`, the CLI auto-creates the project if the name doesn't exist yet — one command, no separate step needed.
13>
14> 🔒 **Every Blob store: `getStore({ name, consistency: "strong" })` — never the string form `getStore("name")`.** The string form defaults to eventual consistency and causes "I just wrote but the next read returns stale/null" bugs. Full rule and rationale: [references/blob.md](references/blob.md) → IRON RULE (top of file).
15
16EdgeOne Makers provides two storage services. **Choose based on your runtime and data type:**
17
18| Storage | Runtime | Data Type | SDK | Use Case |
19|---------|---------|-----------|-----|----------|
20| **KV** | Edge Functions only | Small key-value pairs (≤ 25 MB) | Global variable (no npm) | Counters, config, session tokens, simple CRUD |
21| **Blob** | Cloud Functions (Makers Functions) | Files & objects (images, docs, uploads) | `@edgeone/pages-blob` (npm) | User uploads, AI-generated content, file management |
22
23## Decision Tree
24
25```
26Need to persist anything (records, lists, counters, uploads, save state)?
27├─ Edge Function (V8 runtime, no npm)?
28│ → KV Storage (global variable) → read references/kv.md
29└─ Cloud Function (Node.js, has npm)? ← default for any real backend
30 ├─ Files / images / large objects?
31 │ → Blob Storage → read references/blob.md
32 └─ Structured data (records, lists, counters, per-user state)?
33 → Blob with setJSON / key prefixes → read references/blob.md
34```
35
36## Routing
37
38| Task | Read |
39|------|------|
40| KV Storage (Edge Functions, global variable, put/get/delete/list) | [references/kv.md](references/kv.md) |
41| Blob Storage (Cloud Functions, npm SDK, file upload/download, pre-signed URLs) | [references/blob.md](references/blob.md) |
ahang1598