Storage and saved data
Create storage and choose access
What this is-
Read the site’s current resources with
GET /v1/sites/{sitename}/storage/resources. -
Create or update one resource.
“Add a private notes table where each visitor can read and edit only their own notes.”SendPUT /v1/sites/{sitename}/storage/resources/noteswith the body below. Usekvfor key-value data; file buckets keep presets such aswallfor visitor photos. -
For SQLite, send owner DDL to
POST /v1/sites/{sitename}/storage/sqlite/notes/schema:{"sql":"CREATE TABLE notes (id INTEGER PRIMARY KEY, visitor_id TEXT, text TEXT)"}. -
Review who can read and change data before saving. Permissive policies combine with OR; restrictive policies narrow them with AND. No applicable permissive policy means no access. A table’s own set replaces the default.
{"kind":"sqlite","rules":{"version":1,"policies":[ {"command":"all","using":"visitor_id == auth.id || auth.role == \"owner\"","check":"auth.signed_in"} ]}}
Follow this server’s storage_set_resource description: if it does not accept rules, the server is older and its description says what to send. KV namespaces still in Postgres cannot accept rules. Existing presets work until the announced switch; file buckets keep them afterwards. Saved rules remain enforced if accepting new rules is turned off.
Write to storage from your own code
What this is- Load auth.js and mount sign-in. Use
SH.storage.sqlite('notes').table('notes').add({text:'Hello'})for a visitor insert. - Use
id INTEGER PRIMARY KEY; never supply a visitor row’s primary key orvisitor_id. Declare foreign keys and make the parent readable to the visitor. - Read with
.list()or.get(id); change with.edit(id, values)or.delete(id). Check the returned error code. - Before a larger write, read
GET /v1/sites/{sitename}/storage/usage.
SQLite inserts and references
Use entirely NULL optional composite references, never partly NULL. Keep visitor_id TEXT on parents. Treat unreadable and missing parents alike as invalid_reference. Remove cross-table triggers and cascades from tables visitors edit or delete.
Existing resources and migration
Review legacy identities before migration. Keep unattributed rows outside visitor-owned views. Omit tables to keep existing table sets, or send {} to remove them. Do not mix rules and preset fields in one save.
Rate limits and execution
Retry storage_busy after a short wait; honor Retry-After when supplied. Check SITE_STORAGE_* execution settings in the settings reference. Keep tables accessed by visitors to at most 100 total columns, including server-managed columns. Limit query results.
Quotas and names
Limit file paths to 16 segments; check bucket object allowance, including empty files. Use NFC names for new writes; keep exact legacy names for reads and deletion. Handle sqlite_full separately from site_full.
Global uniqueness and passcodes
A UNIQUE conflict can reveal a hidden row; a KV add attempt can reveal an existing key through key_exists. Use opaque random identifiers for global UNIQUE columns, KV keys, and file paths. Use table routes for visitor SQLite access, not raw SQL. Set site_passcode: "off" only when the owner chooses public resources without unlocking.
A table holds new posts only when its effective rules name TEXT approved_at. Visitor adds store NULL; owner adds stamp the time. Only the owner may edit it to approve. A leftover column no rule names is ordinary data. Edit and delete also require read visibility of the stored row.
Errors you may see
| Code | Means | Do this |
|---|---|---|
use_custom_domain (400 or 401) |
Shared address refuses visitor writes | Open the site on its own address |
invalid_reference (404) |
Parent missing or unreadable | Choose a readable parent |
row_conflict (409) |
Row cannot satisfy a table constraint | Check required fields, unique values, and check constraints |
invalid_rules (400) |
Rules save is invalid | Use rule_error clause and position to repair it |
rules_invalid (403) |
Stored rules no longer compile | Repair the schema or rules with owner tools |
rules_unavailable (400) |
Server rules off or KV still in Postgres | Follow this server’s tool description |
storage_busy (503) |
Storage is busy | Retry after a short wait; honor Retry-After when supplied |
site_full (507) |
Storage allowance reached | Remove unused data |