Merge branch 'v1422/fixes' into release/v1.42.2

docs/api/openapi.yaml

@@ -26952,7 +26952,7 @@ components:
             - ko
         today:
           description: "Optional override of the reference date used to resolve relative phrases (\"tomorrow\", \"next Monday\").
-            Format: `YYYY-MM-DD`. Defaults to the server's UTC day."
+            Format: `YYYY-MM-DD`. Defaults to the account's own day in its time zone."
           type: string
           pattern: ^\d{4}-\d{2}-\d{2}$
       required:

docs/self-hosting/getting-started.md

@@ -77,6 +77,26 @@ process (`pnpm dev` against a host Postgres) or a **custom compose** that
 does not derive it — in that case uncomment and set `DATABASE_URL`
 explicitly in `.env` (see the commented example there).
 
+### Using an existing or shared Postgres
+
+HealthLog can live in a database on a Postgres instance you already run.
+It stores every time as UTC and pins each connection it opens to UTC
+(`TimeZone=UTC`, sent with the libpq `options` startup parameter), so the
+server's or the database's own `timezone` setting does not matter: an
+instance set to `Europe/Berlin` works the same as one set to UTC. The app
+checks the setting at startup and logs a warning naming the zone if a
+connection still reports something else.
+
+Behind PgBouncer with `DATABASE_SESSION_OPTIONS_DISABLED=1` (see
+[Scaling](./scaling.md#postgres-connection-pool-sizing)) the app pins the
+zone with `SET TIME ZONE 'UTC'` on each new connection instead; PgBouncer
+keeps that setting per client in transaction pooling too. If the startup
+warning still appears, set the database default as well:
+
+```sql
+ALTER DATABASE healthlog SET timezone TO 'UTC';
+```
+
 ## 3. Bring the stack up
 
 ```bash

docs/self-hosting/scaling.md

@@ -188,13 +188,16 @@ already`. Either raise `max_connections` on the Postgres side, lower
 `DATABASE_POOL_MAX`, or front the database with PgBouncer in
 transaction-pooling mode.
 
-The app sets its statement timeout and `work_mem` on every connection
-through the libpq `options` startup parameter. PgBouncer refuses that
+The app sets its statement timeout, `work_mem` and `TimeZone=UTC` on every
+connection through the libpq `options` startup parameter. PgBouncer refuses that
 parameter (`unsupported startup parameter: options`) unless it is listed
 in `ignore_startup_parameters`. Either list it there, or set
 `DATABASE_SESSION_OPTIONS_DISABLED=1` so the app sends no session
 settings; set the timeout and `work_mem` on the database role instead
 (`ALTER ROLE healthlog SET work_mem = '16MB'`) if you still want them.
+The time zone is the exception: with the options off the app pins it with
+`SET TIME ZONE 'UTC'` on each new connection, which PgBouncer tracks per
+client, and warns at startup if a connection still reports another zone.
 The measurement maintenance job (Admin, System status) then applies its own
 settings with `SET` after connecting. Its concurrent index rebuild needs a
 session, so run it through a session-mode pool or a direct connection.