Story: Reduce and configure per-service DB connection pool size
Table of Contents
This page documents a story in Sprint 25. It captures the goal, current status, acceptance criteria, and the tasks that compose it.
Goal
Lower the steady-state number of Postgres connections opened by the
service fleet, and make the per-service pool size configurable via
.env instead of hardcoded in the codegen template. Also confirm that
compass services start's systemd integration is still doing the
idiomatic thing, since a recent start showed 5 units racing their
first start attempt.
Status
| Field | Value |
|---|---|
| State | DONE |
| Parent sprint | Sprint 25 |
| Now | Nothing. |
| Waiting on | Nothing. |
| Next | Nothing. |
| Last touched | 2026-08-05 |
Acceptance
- Default per-service pool_size is reduced from its current hardcoded value to shrink each environment's steady-state Postgres connection footprint.
- pool_size is sourced from a CLI flag and an
ORES_<APP>_DB_POOL_SIZEenv var, wired throughdatabase_options=/=database_configuration, no longer a template literal. compass services start's systemd unit/target setup is reviewed against idiomatic systemd practice (unit dependencies, target wants, readiness waits) and any drift found is fixed.
Tasks
| Task | State | Start | End | Description |
|---|---|---|---|---|
| Audit compass services start systemd integration | DONE | 2026-08-04 | 2026-08-04 | Review how compass services start manages systemd units and the service target, confirm it still follows idiomatic systemd practice, and fix any drift. |
| Lower default per-service DB connection pool size | DONE | 2026-08-04 | 2026-08-04 | Reduce the hardcoded pool_size (4) in the service-app codegen template to shrink each environment's steady-state Postgres connection footprint. |
| Make DB connection pool size runtime-configurable | DONE | 2026-08-04 | 2026-08-04 | Move pool_size out of the codegen template literal into database_options/database_configuration, sourced from a CLI flag and ORES_<APP>_DB_POOL_SIZE env var. |
| Unify application.cpp and service initialisation across services | DONE | 2026-08-05 | 2026-08-05 | Clean up application.cpp and service initialisation across all services (including the divergent ores.cli, ores.shell, ores.compute/wrapper shapes), finding commonalities: extract common code to a shared utility, codegen boilerplate that is identical across services, and reduce remaining variation to a minimum handled via variability switches. |
Decisions
- Chose a two-tier design (Option B) over the original capture's
single-tier plan: a fleet-wide default falling back per-service.
Scoped to land in two steps — first the per-service tier alone
(this story's
make_db_pool_size_configurabletask, done), then the fleet-wideORES_DB_POOL_SIZEfallback once PR #1819 (bright_faraday, shared-domain fallback tier inenvironment_mapper_factory) merges, since that PR is the natural home for the fallback mechanism rather than building a one-off. - The 5-of-22-units-race symptom traced to
nats-server's own unit lacking any readiness signal (Type=simple, matching its upstream unit — no sd_notify support), not to anything wrong in the fleet's dependency graph. Fixed with anExecStartPost=port-listen probe on the generatednats-serverunit rather than touching the domain-service units, which were already correctly ordered. application.cpp=/=host.cppunification scoped to the one clear shared-code win (host.cpp's parse/log/construct/run/catch envelope, extracted toores::service::run_host_async()) rather than also implementingconfig/options.hppcomposition unification — that overlaps with E3647ADD's (PR #1819)standard_service_optionsterritory; filed a design recommendation there instead of a second implementation. Onlyores.cli=/ =ores.shellkept hand-written, confirmed real structural divergence (sync execution, custom constructor args), not boilerplate drift —ores.compute/wrapperturned out to fit the uniform shape after all (caught in PR #1855 review, corrected from an initial mis-scoping) and migrated along with the 17 domain services.