fix(backend): stem pool/clustering af op de RIG-Postgres 20-connectie-cap per user

De gedeelde RIG-Postgres (rig-db) capt elke project-DB-user op 20 connecties
totaal (CONNECTION LIMIT 20; max_connections 250, reserved 10). De vorige
defaults (1 worker per core × pool 10) zouden dat budget onder clustering ruim
overschrijden en connecties laten weigeren (too many connections for role).

- WEB_CONCURRENCY default 1 (clustering opt-in i.p.v. één worker per core). De
  app is I/O-bound, dus één proces met een gezonde pool is de beste balans.
- DB_POOL_MAX default 15, ceiling 20 (de per-user cap).
- README: rekensom replicas × WEB_CONCURRENCY × DB_POOL_MAX ≤ ~18, plus
  PgBouncer als route voor echte schaal.

Author: robbertbos

apps/boekhouding-backend/README.md

@@ -27,28 +27,37 @@ Tests draaien tegen een echte Postgres. Zet `TEST_DATABASE_URL`, of laat de defa
 | `CORS_ORIGIN` / `PUBLIC_HOST` | `http://localhost:5174` | Toegestane origin(s), comma-gescheiden lijst mogelijk |
 | `TRUST_PROXY` | `1` | Aantal proxy-hops (voor `req.ip` / rate-limit) |
 | `EXPOSE_API_DOCS` | `false` | Swagger UI + `/api/openapi.json` |
-| **`WEB_CONCURRENCY`** | aantal CPU-cores | Aantal worker-processen (clustering). `1` = uit. Geclampt op `[1, 64]` |
-| **`DB_POOL_MAX`** | `10` | Postgres-poolgrootte **per worker**. Geclampt op `[1, 100]` |
+| **`WEB_CONCURRENCY`** | `1` | Aantal worker-processen (clustering). Standaard 1 (uit); opt-in via `> 1`. Geclampt op `[1, 64]` |
+| **`DB_POOL_MAX`** | `15` | Postgres-poolgrootte **per worker**. Geclampt op `[1, 20]` (de per-user cap) |
 | **`DB_CONNECT_TIMEOUT`** | `10` | Seconden voordat een nieuwe DB-verbinding faalt |
 | **`DB_IDLE_TIMEOUT`** | `30` | Seconden voordat een idle DB-verbinding wordt gesloten |
 | **`RATE_LIMIT_MAX`** | `300` | Verzoeken per IP per minuut (cluster-breed; zie onder) |
 
 Ongeldige/ontbrekende waarden vallen veilig terug op de default.
 
-## Schalen (clustering)
+## Schalen en de connectie-limiet
 
-De server draait standaard één worker per CPU-core (`node:cluster`), zodat de
-beschikbare CPU wordt benut. Migraties draaien éénmalig vóór de workers starten
-(container-CMD: `migrate && index`).
+De gedeelde RIG-Postgres (`rig-db`) staat op `max_connections: 250` met
+`reserved_connections: 10`, en — bindend voor ons — **elke project-DB-user is
+gecapt op 20 connecties** (`CONNECTION LIMIT 20`, ingesteld na een incident waarbij
+één project alle slots opslokte en Keycloak brak). Dat aantal van **20 is dus het
+totale budget over álle pods, replica's en workers samen**.
 
-**Pool-rekensom — belangrijk:** elke worker heeft zijn eigen pool. Zorg dat
+Omdat de app I/O-bound is (lage CPU-load) en DB-werk op de DB-server draait, levert
+**één worker met een gezonde pool** de beste balans — niet veel workers met mini-pools.
+Daarom: `WEB_CONCURRENCY=1` (standaard), `DB_POOL_MAX=15` → 15 connecties bij 1 replica,
+ruim onder 20.
+
+**Rekensom — bewaak het budget:**
 
 ```
-WEB_CONCURRENCY × DB_POOL_MAX  ≤  Postgres max_connections (default 100)  − headroom
+replicas × WEB_CONCURRENCY × DB_POOL_MAX  ≤  ~18   (20 minus headroom)
 ```
 
-(headroom voor migraties, Keycloak en beheer). Voorbeeld: 4 workers × 10 = 40 → ruim
-binnen 100. Een te hoge combinatie kan de database uitputten (self-DoS).
+Wil je toch meerdere cores benutten (clustering), zet dan `WEB_CONCURRENCY > 1` én
+verlaag `DB_POOL_MAX` navenant (bv. 6 workers × 3 = 18). Wil je echt naar veel
+gelijktijdige gebruikers schalen, dan is een **connection pooler (PgBouncer)** de
+juiste route (al voorzien als rig-cluster-*future*) i.p.v. een grotere per-worker-pool.
 
 De in-memory rate-limit is per worker; het entrypoint deelt `RATE_LIMIT_MAX` daarom
 door het aantal workers, zodat de cluster-brede limiet bij benadering gelijk blijft.

apps/boekhouding-backend/src/config.ts

@@ -49,12 +49,15 @@ export const config = {
   exposeApiDocs: process.env.EXPOSE_API_DOCS === 'true',
   trustProxy: parseTrustProxy(),
   databaseUrl: process.env.DATABASE_SERVER_FULL || 'postgresql://parassessment:parassessment@localhost:5432/parassessment',
-  // Postgres connection pool. Defaults match postgres.js but are now explicit and
-  // tunable per deployment. With clustering, size DB_POOL_MAX so that
-  // workers × DB_POOL_MAX stays below the server's max_connections (default 100),
-  // leaving headroom for migrations and other clients.
+  // Postgres connection pool, PER worker process. The RIG shared Postgres caps
+  // each project DB user at 20 connections total (see README), so the total
+  // across all workers AND replicas must stay under that:
+  //   replicas × WEB_CONCURRENCY × DB_POOL_MAX  ≤  ~18 (20 minus headroom).
+  // The app is I/O-bound, so the default is a single worker with a healthy pool;
+  // the ceiling is the per-user cap. Raise the pool / add workers only within
+  // that budget, or put a connection pooler (PgBouncer) in front.
   db: {
-    max: parsePositiveInt(process.env.DB_POOL_MAX, 10, 100),
+    max: parsePositiveInt(process.env.DB_POOL_MAX, 15, 20),
     connectTimeout: parsePositiveInt(process.env.DB_CONNECT_TIMEOUT, 10, 300),
     idleTimeout: parsePositiveInt(process.env.DB_IDLE_TIMEOUT, 30, 86400),
   },

apps/boekhouding-backend/src/index.ts

@@ -1,12 +1,13 @@
 import cluster from 'node:cluster'
-import { availableParallelism } from 'node:os'
 import { buildApp } from './app.js'
 import { config } from './config.js'
 
-// One worker per CPU core by default, so we actually use the available CPU.
-// WEB_CONCURRENCY pins the count (1 disables clustering; lower it when scaling
-// horizontally via replicas instead). The value is clamped in config.ts.
-const workers = config.webConcurrency ?? availableParallelism()
+// Single worker by default. The app is I/O-bound (low CPU), and the shared
+// Postgres caps this DB user at 20 connections total, so each extra worker
+// multiplies connection pressure (workers × DB_POOL_MAX). Opt into clustering
+// by setting WEB_CONCURRENCY > 1, and then lower DB_POOL_MAX so that
+// WEB_CONCURRENCY × DB_POOL_MAX stays within the budget (see README/config.ts).
+const workers = config.webConcurrency ?? 1
 
 if (workers > 1 && cluster.isPrimary) {
   // Migrations already ran once before this process started (the container CMD

apps/boekhouding-backend/test/cov/config.cov.test.ts

@@ -187,38 +187,38 @@ describe('config — parseTrustProxy', () => {
 describe('config — db pool (parsePositiveInt with clamping)', () => {
   it('uses safe defaults when the pool env vars are unset', async () => {
     const config = await loadConfig()
-    expect(config.db).toEqual({ max: 10, connectTimeout: 10, idleTimeout: 30 })
+    expect(config.db).toEqual({ max: 15, connectTimeout: 10, idleTimeout: 30 })
   })
 
   it('accepts a valid override within range', async () => {
-    process.env.DB_POOL_MAX = '20'
+    process.env.DB_POOL_MAX = '12'
     process.env.DB_CONNECT_TIMEOUT = '5'
     process.env.DB_IDLE_TIMEOUT = '120'
     const config = await loadConfig()
-    expect(config.db).toEqual({ max: 20, connectTimeout: 5, idleTimeout: 120 })
+    expect(config.db).toEqual({ max: 12, connectTimeout: 5, idleTimeout: 120 })
   })
 
   it('falls back to the default for a non-numeric value', async () => {
     process.env.DB_POOL_MAX = 'abc'
     const config = await loadConfig()
-    expect(config.db.max).toBe(10)
+    expect(config.db.max).toBe(15)
   })
 
   it('falls back to the default for a value below 1 (e.g. 0)', async () => {
     process.env.DB_POOL_MAX = '0'
     const config = await loadConfig()
-    expect(config.db.max).toBe(10)
+    expect(config.db.max).toBe(15)
   })
 
-  it('clamps a value above the maximum (pool capped at 100)', async () => {
+  it('clamps a value above the per-user cap (pool capped at 20)', async () => {
     process.env.DB_POOL_MAX = '500'
     const config = await loadConfig()
-    expect(config.db.max).toBe(100)
+    expect(config.db.max).toBe(20)
   })
 })
 
 describe('config — webConcurrency (parseWebConcurrency)', () => {
-  it('returns null when WEB_CONCURRENCY is unset (entry point defaults to CPU count)', async () => {
+  it('returns null when WEB_CONCURRENCY is unset (entry point defaults to 1 worker)', async () => {
     const config = await loadConfig()
     expect(config.webConcurrency).toBeNull()
   })