|
| 1 | +--- |
| 2 | +"@objectstack/service-datasource": minor |
| 3 | +--- |
| 4 | + |
| 5 | +feat(datasource): size the SQL connection pool from `OS_DATABASE_POOL_MAX` |
| 6 | + |
| 7 | +A multi-replica deployment had no supported way to raise the number of database |
| 8 | +connections each replica opens. The reporter measured a live 3-replica cluster |
| 9 | +whose authed data API plateaued at ~25 rps while Postgres held only ~9-21 of its |
| 10 | +200 connections: the ceiling was the client pool, and the operator had no knob |
| 11 | +for it. Adding replicas raised the ceiling; sizing the pool — the cheap half — |
| 12 | +was not expressible at all. |
| 13 | + |
| 14 | +The pool for a `postgres` / `mysql` datasource is built by `buildSqlPool`, which |
| 15 | +gives every datasource that declares no `pool` block an explicit `{min: 0, |
| 16 | +max: 5}`. That includes the primary datasource: the one behind |
| 17 | +`OS_DATABASE_URL` is composed as a url and nothing else, so `max: 5` per replica |
| 18 | +was the effective ceiling on every self-hosted deployment, and it was reachable |
| 19 | +only by hand-authoring a `pool` block onto a datasource the operator does not |
| 20 | +write. |
| 21 | + |
| 22 | +`buildSqlPool` now reads `OS_DATABASE_POOL_MAX`. Precedence is a declared |
| 23 | +`pool.max` first, then the env, then today's `5` — an operator knob does not |
| 24 | +override what an author wrote about their own datasource, and it is the only |
| 25 | +site that decides the unspecified case, so the ordering is expressed once. |
| 26 | + |
| 27 | +**Nothing changes when the variable is unset**, which is the upgrade path for |
| 28 | +every existing deployment: the pool stays exactly `{min: 0, max: 5}`, pinned by |
| 29 | +a test whose job is to stay red if that ever drifts. A blank value is read as |
| 30 | +unset, so a declared-but-unfilled compose variable keeps today's behaviour too. |
| 31 | + |
| 32 | +A value that is not a positive integer refuses the boot, naming the variable, |
| 33 | +the value it rejected and the sizing rule — rather than the lenient |
| 34 | +`Number(process.env.X ?? default)` shape, where a typo becomes `NaN` and the |
| 35 | +operator who was trying to raise the ceiling silently keeps the one they meant |
| 36 | +to leave. A pool ceiling is only ever measured in production. |
| 37 | + |
| 38 | +Size it with `replicas × OS_DATABASE_POOL_MAX` below the database's |
| 39 | +`max_connections`, leaving headroom for migrations and admin connections. |
| 40 | + |
| 41 | +Only `postgres` / `mysql` are affected — they are the two arms that build a |
| 42 | +pool. `memory` / `sqlite` / `sqlite-wasm` / `turso` receive no pool parameter |
| 43 | +and reject a declared one outright; the env is read inside a function those arms |
| 44 | +never call, so it cannot reach them. `OS_DATABASE_POOL_MIN` is deliberately not |
| 45 | +exposed: this path already runs `min: 0`. |
0 commit comments