Repository navigation
ADR 0015
github-actions[bot] edited this page Nov 21, 2026
·
1 revision
Status: superseded · Built: done · Date: 2026-11-08 · Superseded by: 0034
First stateful service for hosted apps; backups were decided in ADR 0030. As built, the app's database password is kept in apps//secrets.json (mode 600) rather than app.json, so the agent's API never returns it.
Hosted apps are stateless containers (ADR 0007), so an app that needs to remember anything, starting with guest accounts (ADR 0016), has nowhere to keep it. A database per app inside each app's own stack would multiply memory use and backups by the number of apps; a hosted database service would add a monthly cost for each.
-
One Postgres runs on the apps server: the official image pinned by digest, a named volume,
a memory limit and settings for a small server. It sits on
spotcraft-edgeaspostgresand is never published. It is hardened like the other services as far as the image allows. -
An app asks for a database with
database: truein its spec. The agent then creates a roleapp_<name>and a databaseapp_<name>owned by it, revokesCONNECTfromPUBLIC, applies theauthschema (ADR 0016), keeps the generated password inapp.json, and gives the appDATABASE_URL. Doing this again changes nothing. -
The agent connects as
spotcraft_agent, which may create databases and roles but is not a superuser. Its password,POSTGRES_AGENT_PASSWORD, lives in.envand the deploy environment. - The provisioning code is shared with the local stack (ADR 0017), so a database looks the same on a laptop as on the server.
- Each app role has a connection limit and a
statement_timeout, so one app can't starve the others. - When the agent starts, it brings every app database to the latest
authmigration. - Deleting an app keeps its database unless the request asks to purge it; the dashboard confirms a purge a second time.
- Apps stay stateless containers; their data lives in one place on the apps server.
- Postgres is a shared failure point: when it is down, every app with a database is down.
- A major Postgres upgrade needs a dump and restore; that procedure gets documented.
- Losing the apps server now loses app data, not only configuration. Backups are the next decision.
Published from docs/. Edit the files there; changes here are overwritten.