Databases and instances
An Identity app's catalog (what you declared) is not the same thing as the Postgres that serves it. Catalog rows are keyed by (organization_uuid, identity_app_uuid). Serving happens on a backend the catalog points at — you never name a host, a DSN, or an instance id.
Two backend kinds
backend_kind | What it is | What you get |
|---|---|---|
shared | The app's schema on the platform serving plane | Structure and records work. Direct SQL logins and host-level ops stay limited. |
dbhost | The app's own Postgres instance on an App Data host | Dedicated instance, process DATABASE_URL, Query credentials, pause/resume |
You do not pick a VM. appdata.instance.provision chooses a host that still has capacity and binds the app's catalog databases to that instance.
farm, relay, …) is a slug in the virtual structure. An instance is the physical Postgres. One app has one instance. Several logical databases on that app share it.Provision
Org-member token, MCP, or the console (App Host → Postgres, or Query):
discover appdata.instance.provision
get schema
start — identity_app_uuid
watch
Provision is idempotent. If the app already has an instance, the same run returns it.
What provision does not do: copy rows, compile tables, or mint a process login. It creates an empty instance with the standard roles and points the catalog at it. Schema and data move with migrate.
Exact fields live in the catalog under appdata.instance.*.
After provision
| Workflow | What it does |
|---|---|
appdata.instance.status | Catalog + live host facts (state, connections, disk). Read-only enough to poll. |
appdata.instance.migrate | Compile the app's declared structure onto the instance (and move off the shared plane when that is the path). |
appdata.instance.ensure-system-tables | Replay platform system tables (audit, idempotency) on the instance. |
appdata.instance.pause | Pause a dbhost instance. |
appdata.instance.resume | Resume a paused instance. |
data.appdata.structure.apply still declares tables. On a dbhost app it also executes serving DDL on that instance, not on a DSN you supplied.
What is not in the catalog
There is no appdata.instance.backup or .restore workflow. Host-level dump exists internally; it is not a customer verb yet. Do not plan a restore drill as if it were shipped.
Attach to App Host
A launched process and Buzz read Postgres as DATABASE_URL on the site. That login is appdata.credential.ensure-app (writable, one per app, rotated on re-attach). It is not the read-only login from Query.
See App Host → App Data.