# perch (portable durable objects) > One SQLite file holding a Durable Object’s code and data. The `perch` binary (Rust, V8 via deno_core, SQLite via rusqlite) > runs the object locally, exposes it to agents over MCP, and exports it to > Cloudflare with the class source unchanged. Version 0.1.0. File format_version 1, api_version perch-v0. ## The file An object file is a plain SQLite database. Tables named `_obj_*` are reserved for the runtime; every other table is the object's own data, created only by migrations and reached by object code through `ctx.storage.sql`. - `_obj_meta` (key, value): format_version (1), api_version (perch-v0), name, class, main (src/index.ts), created_at and live_checkin, the id of the code that runs. - `_obj_blobs` (hash, size, data): Every source file version, keyed by its SHA-256. A file that does not change between check-ins is stored once. - `_obj_checkins` (id, parent, manifest, message, created_at, schema): Fossil-style check-ins: a manifest maps each path to a blob hash, parent links the history, and the id is the SHA-256 of the check-in. schema snapshots the data tables the code was released against, which is what rollback checks. - `_obj_migrations` (seq, name, sql, checkin, applied_at): Ordered SQL migrations, each tied to the check-in that brought it. They only move forward; nothing undoes one. - `_obj_kv` (key, value): The key-value half of storage. Values are UTF-8 JSON that any runtime can read; Date, Map, Set, bytes, bigint and the rest are tagged with $perch, so what structuredClone accepts round-trips (cycles are refused). - `_obj_alarms` (id = 1, scheduled_at, retry_count): At most one row: when alarm() is due next. ctx.storage.setAlarm writes it. - `_obj_changes` (id, at, event, checkin, changeset): Every event that writes runs under a SQLite session; its changeset (data tables and _obj_kv) is stored here in the same transaction, with the check-in that produced it. Data table rules: every table needs a declared PRIMARY KEY; AUTOINCREMENT is refused; use UUIDv7 TEXT keys (build v7 from Date.now() plus crypto.getRandomValues; crypto.randomUUID() is v4). Migrations are ordered, named, forward-only SQL. Preview: propose_change works on a sibling copy, `.preview`. ## Writing an object - Entry file `src/index.ts` exports the class named in `_obj_meta.class`, extending `DurableObject` from "cloudflare:workers". Constructor is (ctx, env); call super(ctx, env). - Single-threaded; each event (fetch, RPC, alarm) is one SQLite transaction. - public/: static files served before fetch() without waking the object (Cloudflare Static Assets rules) - fetch(request): every other HTTP request; import page from "./page.html" for templates - public methods: RPC, also POST /.perch/rpc/ with a JSON array of args - ctx.storage.sql.exec: cursor with toArray, one, raw, rowsWritten - ctx.storage.get / put / delete / list: the KV half - setAlarm / getAlarm / deleteAlarm, alarm(): fired on schedule by perch run - transactionSync, blockConcurrencyWhile: atomic writes, guarded startup - Globals: Request, Response, Headers, URL, URLSearchParams, TextEncoder, TextDecoder, crypto.randomUUID, crypto.getRandomValues, setTimeout, structuredClone, atob, btoa, console. - A SQLite authorizer refuses, from object code: any access to `_obj_*` tables, DDL (CREATE/ALTER/DROP), BEGIN/COMMIT/SAVEPOINT, ATTACH, and all pragmas except read-only introspection (table_info, table_xinfo, table_list, index_list, index_info, index_xinfo, foreign_key_list). - Keep the class Cloudflare-compatible: `perch export` deploys the same source. ## HTTP surface (perch run, and the perch export worker) - GET/HEAD requests that match a file under `public/` are served as-is, before fetch() and without waking the object, with Cloudflare Static Assets' defaults: `/` is public/index.html, `/about` is public/about.html, `/about.html` 307s to `/about`, `/docs/` is public/docs/index.html and `/docs` 307s to it. Strong ETag (the file's SHA-256), 304 on If-None-Match, `Cache-Control: public, max-age=0, must-revalidate`. On export, public/ becomes `assets.directory`. - Every other request goes to the class's fetch() (a 404 if it has none). - Templates import as strings: `import page from "./page.html"` (also .txt, .sql, .css, .md, .svg). Binary files go through propose_change as `{ "base64": "..." }`; 25 MiB per file. - `POST /.perch/rpc/` with a JSON array body calls a public method and returns `{"result": ...}`. constructor, fetch, alarm, ctx, env and names starting with `_` are not RPC. ## MCP (`perch mcp `, stdio, JSON-RPC 2.0, one message per line) Workflow: describe_object, read_code, propose_change (code + tests + migrations on the preview; stored tests run), read_object and test_call (reads and writes on the preview), release_change (live; refused while a stored test fails). rollback_code moves code back if it still fits the schema. undo_changes reverses recent data changes. read_object reads live; call_object writes to it. - `describe_object` [read]: Name, class, live check-in, tables with columns and row counts, files, next alarm, preview state. Start here. - `read_code` [read]: Files at the live check-in, the preview, or any check-in id (a 4+ character prefix works). Binary files come back as base64. - `list_checkins` [read]: History, newest first, with the migrations each check-in added. Unified diffs on request. - `query_data` [read]: Read-only SQL over the object’s own tables, live or preview. At most 500 rows. - `propose_change` [destructive]: Changes the preview copy only. Whole files, exact-string edits and new migrations, applied to a preview copy of the file (live data included), built there, stored tests run. Proposals stack; restart starts over from live. - `test_call` [destructive]: A write call on the preview copy: POST, PUT, PATCH or DELETE to fetch(), an RPC method, or alarm(). Returns the result, console logs and the rows each table gained, changed or lost. - `read_object` [read]: A read of live or the preview: GET or HEAD to fetch() or public/, or an RPC method. The runtime refuses any write made during it and saves nothing. - `run_tests` [read]: Runs the object’s test/*.ts files. Each test gets its own fresh, empty copy of the object and a clock it controls. - `list_changes` [read]: Recent data changes on live: the event, the time, rows per table, and whether each can be undone. - `undo_changes` [destructive]: Reverses a data change and every newer one in one transaction. Refused across a migration. Recorded, so an undo can be undone. - `release_change` [destructive]: Runs the preview’s migrations on the live file and moves live to its code, squashed into one check-in, in one transaction. Refused if the preview did not build, a stored test fails, or live moved. - `rollback_code` [destructive]: Moves live back to an earlier check-in. Code only, never schema: refused when that code no longer fits the tables. - `call_object` [destructive]: A write call on the live object: POST, PUT, PATCH or DELETE to fetch(), or an RPC method. Annotations follow Anthropic's connector directory rules: every tool has a title and exactly one of readOnlyHint or destructiveHint. Read-only: describe_object, read_code, list_checkins, query_data, read_object, run_tests, list_changes. Destructive (anything that modifies data, the preview copy included): propose_change, test_call, undo_changes, release_change, rollback_code, call_object. Reads and writes are separate tools. read_object takes GET or HEAD (or an RPC method) on live or the preview, and the runtime refuses any SQL write, key-value write or alarm change made during it. test_call (preview) and call_object (live) take POST, PUT, PATCH or DELETE, or an RPC method; test_call also takes kind alarm. Edits: propose_change takes `edits: [{ path, old, new, replace_all? }]`. `old` must match the file exactly and occur once. Use these after the first version, not whole files. Stored tests: files under `test/` that `import { test, expect } from "perch:test"`. Each `test(name, async (obj) => …)` runs on its own fresh, empty copy of the object. `obj` has `fetch(path, init)` (an object body is a JSON POST), `rpc(method, ...args)`, `alarm()`, `sql(query, ...bindings)`, `storage`, and `clock.set/advance/now` (Date.now() follows it). `expect` has toBe, toEqual, toBeTruthy, toBeFalsy, toBeNull, toBeDefined, toContain, toHaveLength, toBeGreaterThan, toBeLessThan, toMatch and .not. Example client config: `claude mcp add todo -- perch mcp todo.perch` ## CLI - `perch new [--class C] [--name N] [--from DIR]`: Create an object file: an empty class, or src/**, public/** and migrations/*.sql from a directory. - `perch run [--port 8787] [--host 127.0.0.1] [--no-alarms]`: Serve it over HTTP and fire its alarms. - `perch mcp `: The MCP server, over stdio. - `perch describe `: The description as JSON. - `perch checkins [--limit 20] [--diffs]`: Code history. - `perch call [json-args]`: Call an RPC method on the live object. - `perch fetch [-X METHOD] [-d BODY]`: Send one request to the live object’s fetch(). - `perch test `: Run the stored tests, each on a fresh empty copy. Exit 1 on failure. - `perch changes [--limit 20]`: Recent data changes. - `perch undo `: Reverse that data change and every newer one. - `perch export [--worker-name W]`: Write the live code as a Wrangler project. `perch export` writes `src/**` byte for byte, `perch/worker.js` (a wrapper that applies migrations once per object, tracked in `_perch_migrations`, and serves the RPC route), `perch/migrations.js` and `wrangler.jsonc` with one SQLite-backed Durable Object binding. Deploy with `bunx wrangler deploy`. ## Out of scope in v0 - WebSockets - env bindings and outbound fetch - npm imports (relative imports between the object’s own files work) - a server mode hosting many object files - sync between copies of a file - moving state to or from Cloudflare (export moves code and migrations, not data) ## Pages - https://perch.proc.io/ : overview and quick start - https://perch.proc.io/run : open a .perch and run it in the browser (SQLite as WebAssembly, the same bootstrap as the native runtime; nothing is uploaded) - https://perch.proc.io/format : the _obj_ tables