Decision guide

Where should this site’s data go?

It is not all one blob. A Simple Host site keeps data in three separate places: files on disk, one JSON document, and a table of rows. Only the document is a single blob.

Three stores for one Simple Host site. Files are a stack of versions: current points at v3, rollback points back at v2. State is one document: a write to a single field rewrites the whole document, capped at 1 mebibyte. Collections are separate rows: a write adds one new row and leaves the rest untouched, 64 kibibytes per row with no count limit. 1 Files versioned directories v3 current v2 rollback v1 new deploy → new version nothing is overwritten 2 State one JSON document { votes: 14 write · one field theme: "dark" title: "…" } 1 MiB max the whole box is rewritten every write rewrites all of it even incrementing one counter 3 Collections one row per item new item write · one insert item · untouched item · untouched … 64 KiB per row · no limit only the new row is written existing rows stay untouched Three stores for one Simple Host site, stacked. Files are a stack of versions: current points at v3, rollback points back at v2. State is one document: a write to a single field rewrites the whole document, capped at 1 mebibyte. Collections are separate rows: a write adds one new row and leaves the rest untouched, 64 kibibytes per row with no count limit. 1 Files versioned directories v3 v2 v1 current rollback new deploy → new version nothing is overwritten 2 State one JSON document { votes: 14 write · one field theme: "dark" title: "…" } 1 MiB max · the whole box is rewritten every write rewrites all of it even incrementing one counter 3 Collections one row per item new item write · one insert item · untouched item · untouched … 64 KiB per row · no limit only the new row is written existing rows stay untouched
Three stores, one site. A state write lights up the whole document. A collection write adds one row.

1Files — what you deployed

Stored as versioned directories on disk: <site>/v1, <site>/v2, and so on, with current pointing at the live one. Every deploy writes a new version. Nothing is overwritten.

Rollback re-points current at an older version. Instant, and nothing is lost.

This is your HTML, CSS, images, PDFs — anything in the upload.

2State — one small document per site

Stored as a single JSON document in one database column (sites.state), plus a version number. Hard cap: 1 MiB (1,048,576 bytes) for the entire document.

You can change any part of it by path: set a value, increment a number, append to a list, remove a key. You can also read just one branch (/state/votes) instead of the whole thing.

Every write rewrites the whole document, however small the change. Incrementing one counter rewrites everything in it. That is the single most important fact on this page.

It has a version, so two writers cannot silently clobber each other. You can delete from it. Removing a key is a normal operation.

Good for: a counter, a vote tally, a small set of settings, a handful of values.

3Collections — lists that grow

Stored as one database row per item (collection_items), not as one document. 64 KiB per item. No limit on how many items.

Adding an item is a single insert. It does not rewrite anything that already exists, so a collection with 10,000 entries costs the same per write as one with 10.

Reads are paginated: 50 per page by default, 200 maximum, with a cursor to walk backwards through the rest.

Append-only. You cannot edit or delete an item — not as a visitor, not as the site owner, not as an admin. Every such request returns 405. The only way to remove one entry is to delete the entire site.

Good for: RSVPs, sign-ups, guestbook messages, orders, anything that accumulates.

Side by side

Files State Collections
Shape Versioned directories on disk One JSON document One database row per item
Size limit The files you uploaded 1 MiB (1,048,576 bytes) for the entire document 64 KiB per item; no limit on how many
Cost of a write A new version directory The whole document is rewritten One insert; existing rows untouched
Can you delete Versions stay. Rollback moves current. Yes. Removing a key is a normal write. No. Edit and delete return 405. Only deleting the site removes an item.
How you read it The live current version The whole document, or one branch such as /state/votes Pages of 50 (max 200), walking backwards with a cursor
Good for HTML, CSS, images, PDFs A counter, a tally, a handful of settings RSVPs, sign-ups, guestbook messages, orders

Which do I use?

Two limits to plan around: a collection item cannot be removed once written, and state is capped at 1 MiB for everything combined.