Database administrator
You own the PostgreSQL that the platform keeps its lasting state in: Access's tables, Data's records with their audit, events and version history, and, when the gateway is configured for it, the gateway's shared state. This page lists what you are responsible for, what to read first and where each database task is documented.
What you own#
| Database | Who connects | Connection variable | What it holds | Rules |
|---|---|---|---|---|
| Access | Access replicas | ACCESS_DATABASE_URL | Eight tables: tenants, principals, permissions, grants, groups, roles and the two role link tables | Access spec §3 |
| Data | Data replicas and workers | DATA_DATABASE_URL, DATA_REGISTRY_DATABASE_URL, DATA_DELIVERY_DATABASE_URL | Workspace records, audit, events, deliveries and version history, kept apart per workspace by row-level security | Data spec §6.4, §7 |
| Gateway shared state (optional) | Gateway replicas and gateway-control | GATEWAY_SESSION_URL, GATEWAY_SHARED_STATE_URL, GATEWAY_CONTROL_STATE_URL with a postgres:// URL | Sessions, rate-limit windows, cached decisions and route-table revisions | Gateway spec §12.8 |
Each service connects with its own non-superuser role. Access refuses a superuser or a BYPASSRLS role in production, because row-level policies would not bind it (Access spec §3.10).
Start here#
- Platform overview, for where each database sits.
- Access operations: database role and Data operations: database roles, to create the roles.
- Data configuration: database, for the three Data connections and what each role may do.
- Gateway operations: shared state, if the gateway uses PostgreSQL rather than Redis.
- Back up and restore, before the first production write.
Common tasks#
| Task | Where |
|---|---|
| Create the roles and databases of a first deployment | Deploy the platform |
| Run migrations and detect drift | Data: migrations and drift, Access spec §3.8 |
| Back up, restore and rehearse | Back up and restore |
| Apply retention and remove a workspace's data | Data: retention, Data: remove a workspace |
| Clean up failed event deliveries | Data: failed deliveries |
| Size pools and timeouts | Data configuration: budgets, Access operations: tuning, Gateway configuration: shared state |
| Upgrade with new migrations, or roll back | Upgrade and roll back |
| Rotate database passwords | Rotate secrets |
Reference#
| Question | Page |
|---|---|
| What does each Access table hold, and which indexes serve decisions? | Access spec §3, §8.5 |
| Which fields does Data maintain itself, and how does a collection change? | Data spec §7 |
| How does Data scope every statement to one workspace? | Data spec §6.4 |
| What does Data keep, and for how long? | Data spec §15.4 |
| Why does Data's SQL look the way it does? | Data decisions: implementation decisions |
| How do the two gateway backends compare? | Gateway spec §12.6 |
When the database is the problem#
| Symptom | Where to look |
|---|---|
Data answers 503 DATABASE_UNAVAILABLE | Data troubleshooting |
Data's readiness probe answers 503 | Data troubleshooting |
| Access refuses to start because of its database role or schema | Access troubleshooting: start refusals |
| Gateway sessions or limits fail with the shared-state backend | Gateway troubleshooting: startup and readiness |
The rules a request follows are not yours to change; the schema they run on is. When the two meet, as in an index Data needs or a migration Access refuses, the owning spec decides.