docs: describe the app's database role, its limits and how to opt out

This commit is contained in:
Marc-André Bombeck committed 2026-11-03 20:38:46 +01:00
1 parent c7ff22ab00
commit df1e19f1c2
5 files changed
+156 -1

No files matched your search

+16
View File
@@ -140,6 +140,22 @@ An INVALID index whose migration is already recorded applied is not touched at
boot. The boot names it on stderr with `WARNING — index … is INVALID`; rebuild
it with `REINDEX INDEX CONCURRENTLY "<index>";` when the database is quiet.
### The app's database role
The steps above run as the owner `DATABASE_URL` names: the dump, the
migrations and, after them, the setup of `healthlog_app`, the role the app
then connects as ([database-role.md](../self-hosting/database-role.md)). The
app never runs a migration. A migration that creates a table needs nothing
more: the setup grants the role every table it lacks before the app starts.
On the first start of the release that brings the role, the setup hands the
existing `pgboss` tables to it, which takes each table's lock for a moment.
Stop the old container (and a separate worker) before the new one starts, as
for any update with migrations; a lock that does not come within 15 seconds
leaves that start on the owner with a notice, and the next start tries again.
A web container and a worker container that start together wait for each
other on an advisory lock and derive the same password.
### v1.46.0 notes
- **Postgres 18.** The compose file moves the bundled database from
+8
View File
@@ -147,6 +147,14 @@ different.
Sign in. The app's own key check runs at start and refuses to serve on a
key that does not open the data.
The restore runs as the owner `DATABASE_URL` names, and the restored tables
belong to it. The app connects as `healthlog_app`
([database-role.md](../self-hosting/database-role.md)): the start in step 5
grants that role the restored tables and hands it the queue schema before the
app runs. A dump carries grants to `healthlog_app`; `db-restore` leaves them
out (`--no-owner --no-privileges`). Restoring with `pg_restore` by hand, pass
the same two flags, or it fails on a database without the role.
When the dumps are still in the server's `backups` volume (the database
volume was lost, the backups volume was not), step 4 is
`docker compose run --rm db-restore latest`.
+11 -1
View File
@@ -214,7 +214,7 @@ So an index is retired in two halves (v1.43.8, migration 0416, for
exactly as the schema does, and `prisma migrate dev` / `migrate diff` see
no drift and generate nothing.
2. The index name goes into `RETIRED_MEASUREMENT_INDEXES` in
`src/lib/jobs/measurement-maintenance.ts`. Every run of this job, the
`src/lib/jobs/retired-measurement-indexes.mjs`. Every run of this job, the
nightly 03:40 check included, drops each name still present with
`DROP INDEX CONCURRENTLY IF EXISTS`, waiting at most 60 seconds for its
locks. A run that runs out of time leaves the index (possibly marked
@@ -242,6 +242,16 @@ SET lock_timeout = '60s';
DROP INDEX CONCURRENTLY IF EXISTS "measurements_user_id_type_measured_at_idx";
```
When the app connects as its restricted role
([database-role.md](../self-hosting/database-role.md)), the job may vacuum and
rebuild (`MAINTAIN`) but not drop: `DROP INDEX` belongs to the table's owner.
A run then skips the drops, of retired indexes and of the invalid copy a
failed rebuild leaves, names what it found under
`maintenance_drops_left_for_boot` with a warning, and the next start drops
each as the owner with `DROP INDEX CONCURRENTLY`, waiting at most five
seconds. Until then a failed rebuild's copy holds its disk; restart the
container, or drop it by hand as the owner with the statement above.
For the next large index, follow the same two halves.
`src/__tests__/migration-lock-timeout-guard.test.ts` refuses a
`DROP INDEX CONCURRENTLY` in any migration and requires every retired name to