Skip to content

Darling: the PostgreSQL store's minimum version is 16, stated once in the README (#4982) - #4988

Merged
erikdarlingdata merged 1 commit into
devfrom
fix/4982-pg-minimum-version
Oct 3, 2026
Merged

erikdarlingdata merged 1 commit into
devfrom
fix/4982-pg-minimum-version

Conversation

@erikdarlingdata

@erikdarlingdata erikdarlingdata commented Oct 3, 2026 •

Copy link
Copy Markdown
Owner

Closes #4982.

Why

Three places gave three different minimum PostgreSQL versions for the store:

  • Darling/README.md, Prerequisites, said PostgreSQL 16 or newer is "recommended".
  • Darling/README.md, the systemd section, said PostgreSQL 15+.
  • Six code comments said the product minimum is 17.

Nothing in the code checks the store's version when the service starts, so there was no check to read the number from. I took the minimum from what the store has to run. It is 16.

Evidence (file:line at the base commit):

What the store needs Where Needs
NULLS NOT DISTINCT in two migration rungs that always run (V143 and V145) PgMigrations.cs:2349, :2527 15
any_value() in the analysis reads against the store, with no version check PgFactCollector.QueryPerf.cs:389, :429; PgDrillDownCollector.Queries.cs:733-734, :765-766 16
TimescaleDB 2.29.0 removed PostgreSQL 15: "This release supports PostgreSQL 16, 17, and 18." The bundle pins 2.30.1 Darling/tools/fetch-pg-runtime.ps1:108; TimescaleDB 2.29.0 release notes 16
The BRIN index on the per-interval Query Store table is built only from 16 (skipped below it, not an error) QueryStoreIntervalWideBrinIndex.cs:82 16

On 15 the plan-regression read fails and is reported as a collection failure (PgFactCollector.QueryPerf.cs:660-665), so that server loses those findings.

Nothing that always runs needs 17:

  • pg_stat_checkpointer is read on 17 and later, with a pg_stat_bgwriter read below (StoreSelfMetrics.cs:475, :608, :1264).
  • transaction_timeout appears only in a comment, as the reason it is not used (PgMigrations.cs:7085).
  • A sweep of the Storage, Service, Viewer and Analysis code for 17 and 18 features found no use of MERGE ... RETURNING, JSON_TABLE, JSON_EXISTS, JSON_QUERY, JSON_VALUE, uuidv7, RETURNING OLD/NEW or pg_maintain.
  • The "minimum is 17" claim first appears in the analysis commits e61c44f59 and 8d3ae43f3, and Field data confirms the interval-table fix removes the spill, ship it (#3953) #4208 (731512799) copied it into the V143 comment. None of the six comments cites a check or a feature that needs 17.

I looked for a version check to raise and found none. SHOW server_version_num in DarlingStoreUpgrade.cs:5395 only compares the running major with the bundled one after a managed upgrade. DarlingStoreHostProfile.cs:422 only reports the version. The probe in DarlingServerConnector.cs is for monitored targets. So I did not add a check.

Checked and left alone:

  • docs/postgres-first-target-runbook.md says PostgreSQL 13+ and 14+. Those are floors for a monitored PostgreSQL target, not for the store.
  • HypotheticalIndexExperiment.MinimumPostgresMajorForGenericPlan = 16 is also a monitored-target floor.
  • Darling/compose/docker-compose.yml uses a PostgreSQL 17 image, which meets the minimum.
  • The CLI help and darling.sample.json make no claim about the store's minimum. The sample only names the bundled PostgreSQL 18.

What changes

  • Darling/README.md, Prerequisites (line 40): states the minimum once ("the minimum is PostgreSQL 16, and the service is developed and validated against PostgreSQL 18") and breaks the long sentence into short ones. The text about the login, the TimescaleDB background workers and random_page_cost is the same apart from those breaks.
  • Darling/README.md, systemd section (line 177): "PostgreSQL 15+" becomes a pointer to Prerequisites.
  • The comments that said "the product minimum is 17" now say 16: PgMigrations.cs, PgFactCollector.cs, PgFactCollector.QueryPerf.cs, PgDrillDownCollector.cs, and one comment each in DarlingAnalysisPipelineTests.cs and PgFactCollectorTests.cs. No assertion changes.
  • No run-time change and no new check. The README sentence that the BRIN index is skipped below 16 is unchanged and still true: the service does not refuse an older store, it skips that one index.

Test plan

  • Build Darling/Darling.Tests/Darling.Tests.csproj -c Debug: 0 Warning(s), 0 Error(s).
  • DarlingCollectorToggleVerbTests, RepoFileAdoptionTests, DocCommentHygieneTests, DarlingAnalysisPipelineTests, PgFactCollectorTests: Total 139, Failed 0, Skipped 4 (live PostgreSQL tests that skip when no connection string is set; none was set).
  • ReadmeDerivedCountPinTests and DarlingCliCommandsTests (they read the README): Total 25, Failed 0.
  • Plain-English check on README lines 40 and 177: the sentences I wrote have no hits. The remaining hits are existing text (the bold lead-in and dash, the SSD and BRIN sentences, and the systemd paragraph's long sentence).
  • Full Darling test suite: not run, because the change is comments and README text.
  • Live PostgreSQL tests: not run, because no PostgreSQL connection is used.

Notes

  • The minimum is a judgment from the evidence above, not an enforced check. A store on 15 still starts and migrates (V143 and V145 need only 15), but it loses the plan-regression findings and cannot run TimescaleDB 2.29 or later. If you would rather document 15 for stores without TimescaleDB, the README sentence changes to match.
  • I did not add a startup refusal. Refusing a store on 15 would be a behavior change that the issue does not ask for.
  • The TimescaleDB 2.29.0 quote is from the project's release notes on GitHub (releases/tag/2.29.0), fetched during this work.

CHANGELOG

No entry in this PR; the release owner adds it under [Unreleased].

Proposed entry:

SECTION: Fixed
ENTRY:
- **Darling's README now states one PostgreSQL minimum for the store, 16** ([#4988]) - The README said 16 was recommended in Prerequisites and 15+ in the systemd section, and code comments said 17. The minimum is 16: the analysis reads use `any_value()`, which arrived in PostgreSQL 16, and TimescaleDB 2.29 and later no longer supports PostgreSQL 15. Prerequisites now says so once, the systemd section points to it, and the comments match. Nothing changes at run time: the service still does not check the store's version when it starts.
REF:
[#4988]: https://github.com/erikdarlingdata/PerformanceMonitor/pull/4988

… the README (#4982)

The README gave 16 (recommended) in Prerequisites and 15+ in the systemd section, and five code comments said the product minimum is 17. Nothing in the code checks the store's version at startup, so the minimum comes from what the store has to run: any_value() in the analysis reads needs PostgreSQL 16, and TimescaleDB 2.29 and later (the bundle pins 2.30.1) supports PostgreSQL 16 to 18 only. Nothing unguarded needs 17: pg_stat_checkpointer is read on 17 and later with a pg_stat_bgwriter fallback below. Prerequisites now states the minimum once, the systemd section points to it, and the comments say 16.
@erikdarlingdata
erikdarlingdata marked this pull request as ready for review October 3, 2026 04:05
@erikdarlingdata
erikdarlingdata merged commit 8aa3fa2 into dev Oct 3, 2026
20 of 22 checks passed
@erikdarlingdata
erikdarlingdata deleted the fix/4982-pg-minimum-version branch October 3, 2026 04:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant