App Data
App Data is Orkestia's data plane for apps you build on the platform. You declare databases, tables, fields, and ownership. Orkestia stores the rows, binds the caller, and enforces isolation. Your frontend never receives a database credential.
It is the missing half of App Enablement: "Sign in with Orkestia" authenticates the user; App Data is where that user's (or that workspace's) rows live.
data.appdata.*, appdata.*).Why it exists
Vibecoded and product apps need persistent state. Giving those builders a raw Postgres URL, or asking them to write multi-tenant SQL in the browser, is how isolation bugs ship. App Data inverts that:
- You declare a virtual structure (database → tables → fields → ownership).
- Orkestia compiles it into catalog metadata and serving DDL.
- End-user reads and writes are typed workflows (or the Data API / PostgREST on top of those rules).
- The principal is injected server-side from the verified token. A caller cannot pick another user's id.
- Your team can run admitted SQL in Query. That door is org-operator only.
Catalog rows are scoped to (organization_uuid, identity_app_uuid). The physical Postgres is a serving instance (shared or dedicated dbhost) — not a DSN you paste.
Surfaces
| Surface | What you do there |
|---|---|
Structure (data.appdata.structure.apply / .query) | Declare or inspect virtual databases and tables |
Instances (appdata.instance.*) | Own Postgres for the app — provision, status, migrate, pause, resume |
Records (data.appdata.record.*, data.appdata.transaction.apply) | Create, read, query, update, delete rows (soft delete) |
Documents (data.appdata.document.*) | Upload slots, confirm, query, download URLs — end-user files wrapping storage.*, not the Identity app Files tab |
| Data API / MCP | discover → describe → read / create / update / delete / call — no SQL |
| PostgREST HTTP | Standard /rest/v1 with an Orkestia end-user JWT — no DSN |
| Query console | Admitted SELECT and read-only logins at query.orkestia.dev |
| Exposed virtuals | What a browser with an end-user JWT is allowed to start |
What App Data is not
- It is not a DSN you put in frontend source, and it is not a place for end-users to send SQL.
- It is a place for operators to run admitted SELECT in Query, and for a process to use a platform-minted
DATABASE_URL. - It is not Lumen. Lumen stores telemetry; App Data stores your app's business rows.
- It is not your cloud database. Side-effecting cloud data still lives in your accounts, reached through connections and workflows.
- It is not Buzz, and it is not a Chat Relay. Ordered append + membership is the data primitive for streams; Buzz is a Nostr websocket on a different hostname.
- It is not the Identity app Files tab. Org-member objects on site MinIO are
apphost.file.*.document.*is the end-user path that wraps a customerstorage.*bucket. - Backup / restore of an instance is not a catalog workflow yet.
See Security & compliance for the custody boundary. App Data is a deliberate, scoped store: the rows of apps that opted into the platform data plane, isolated by identity and ownership — not a copy of customer cloud data.
To attach this instance to a hosted site (so a process or Buzz can use it) and to browse records in the console, see App Host.
Typical path
1. Provision the identity app identity.app.provision
2. (For a public site) go live identity.app.set-mode → live
3. Claim the site (optional) apphost.site.claim
4. Declare tables data.appdata.structure.apply
5. Dedicated instance when needed appdata.instance.provision → migrate
6. Compose end-user-eligible virtuals composition / DevKit vw
7. Expose them identity.app.expose-virtual-workflow
8. Sign the user in @orkestia/auth
9. Read / write as that user exposed virtual, Data API, or PostgREST
virtual.<uuid>@<version>), never a raw data.appdata.record.write. The catalog type stays on the org / agent side. See Expose.