Skip to content
Docs

Storage and saved data

Create storage and choose access

What this is
  1. Read the site’s current resources with GET /v1/sites/{sitename}/storage/resources.

  2. Create or update one resource.

    “Add a private notes table where each visitor can read and edit only their own notes.”
  3. 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)"}.

  4. 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
  1. Load auth.js and mount sign-in. Use SH.storage.sqlite('notes').table('notes').add({text:'Hello'}) for a visitor insert.
  2. Use id INTEGER PRIMARY KEY; never supply a visitor row’s primary key or visitor_id. Declare foreign keys and make the parent readable to the visitor.
  3. Read with .list() or .get(id); change with .edit(id, values) or .delete(id). Check the returned error code.
  4. 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

Next