fix(pgvector): resolve the deb version from the pgdg pool instead of pinning 0.8.1-2

[automagik-genie]

Root cause

src/postgres.js _installPgvectorFromDeb downloaded a hard-coded postgresql-<major>-pgvector_0.8.1-2.pgdg+1_<arch>.deb. pgdg garbage-collects superseded packages from its pool, so once 0.8.5/0.8.6 shipped the URL 404'd on every start with runtime.enablePgvector=true. The failure was logged as non-fatal and pg_available_extensions simply had no vector, so downstream consumers died at CREATE EXTENSION vector.

Fix

• New pure module src/pgvector-version.js:
  • parsePgvectorPoolListing(html, { pgMajor, arch }) — regex postgresql-<major>-pgvector_(\d+\.\d+\.\d+-\d+)\.pgdg(+|%2B)1_<arch>\.deb over the pool directory listing, deduped, sorted highest first.
  • compareDebianVersions(a, b) — small dpkg-style comparator (upstream then revision, alternating digit/non-digit runs, ~ sorts lowest). No new dependency.
  • resolvePgvectorDebVersions({ pgMajor, arch, env, fetchListing }) — precedence: AUTOPG_PGVECTOR_VERSION pin → pool listing (highest first, remaining versions kept as retries) → fallback list ['0.8.6-1','0.8.5-1','0.8.1-2'] when the listing is unreachable or has no match. Never throws.
• src/postgres.js:
  • _obtainPgvectorDeb honours AUTOPG_PGVECTOR_DEB=<file> (local .deb, no network) and otherwise walks the candidate list, skipping 404s.
  • Resolved version + sourceUrl are written to vector.meta.json so auto-heal can tell "stale for this PG major" from "different pgvector version".
  • Still non-fatal for the postmaster, but the warning now lists every version tried and names AUTOPG_PGVECTOR_DEB=<file> / AUTOPG_PGVECTOR_VERSION=<ver>.
  • Fetches are bounded with AbortSignal.timeout so an unreachable mirror can't stall startup.
• README: documents the resolution + the two env overrides.

Tests

tests/pgvector-version-resolve.test.js (16 tests, fixture listing, no network): highest wins, arch filter, PG-major filter, dbgsym/non-deb entries ignored, +/%2B tolerance + dedupe, comparator ordering (0.8.10-1 > 0.8.6-1, revision, tilde), pin skips fetch, unreachable listing → fallback order, no-match → fallback, URL encoding, local-deb filename parse.

• bun run test: 711 pass, 3 skip, 0 fail (714 tests across 50 files)
• bun run lint: clean
• bun run deadcode: clean

Closes #145

🤖 Generated with Claude Code

https://claude.ai/code/session_014DFsrEGgS79a6ELNUE38Dh

Summary by CodeRabbit

• New Features

  • pgvector installation now discovers compatible package versions dynamically instead of relying on a fixed version.
  • Added support for selecting a specific version or providing a local package through environment settings.
  • Installation records the package source in metadata and success logs.
  • Failed download attempts now provide clearer details and available configuration options.

• Bug Fixes

  • Installations gracefully fall back to known compatible versions when package listings are unavailable or incomplete.

• Documentation

  • Documented Linux package retrieval, version selection, override settings, and installation failure behavior.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Team

Run ID: fd521b3f-fd24-4f83-9936-31506b4d2468

📥 Commits

Reviewing files that changed from the base of the PR and between 7e8d508 and 07f97ba.

📒 Files selected for processing (4)

• README.md
• src/pgvector-version.js
• src/postgres.js
• tests/pgvector-version-resolve.test.js

Included review availability: Your plan provides up to 1 included review per hour; 0 remain after this review.

---

📝 Walkthrough

Walkthrough

The PR replaces the hardcoded pgvector package version with dynamic PGDG pool resolution. It adds version parsing, fallback and override support, retry downloads, source metadata, failure logging, documentation, and tests.

Changes

pgvector installation

Layer / File(s)	Summary
Version resolution and parsing src/pgvector-version.js, tests/pgvector-version-resolve.test.js	Adds Debian version comparison, PGDG listing parsing, package URL and filename helpers, environment version pinning, fallback versions, bounded listing fetches, and resolver tests.
Installer download and metadata integration src/postgres.js, README.md	The installer supports local .deb files, resolves and retries candidate versions, records sourceUrl, expands failure logs, and documents the override variables and fallback behavior.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Merge Risk: ⚪ Minimal · up to 07f97

This change replaces a stale pgvector package pin with version resolution and bounded fallbacks, while documenting overrides and adding tests; no actionable merge-blocking risk remains.

Sequence Diagram(s)

sequenceDiagram
  participant PostgreSQLInstaller
  participant VersionResolver
  participant PGDGPool
  participant DebianPackage
  PostgreSQLInstaller->>VersionResolver: Resolve pgvector versions
  VersionResolver->>PGDGPool: Fetch package listing
  PGDGPool-->>VersionResolver: Return matching versions
  VersionResolver-->>PostgreSQLInstaller: Return ordered candidates
  PostgreSQLInstaller->>DebianPackage: Download candidates with retries
  DebianPackage-->>PostgreSQLInstaller: Return package bytes or failure

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 58.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 12 functions across 3 files. (1 skipped: …	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the primary change: resolving the pgvector Debian version from the pgdg pool instead of using the obsolete 0.8.1-2 pin.
Linked Issues check	✅ Passed	The changes satisfy issue [#145]. They replace the hard-coded pgvector version with pool-based resolution, known-version fallback, retry handling, and environment overrides. This addresses package rem…
Out of Scope Changes check	✅ Passed	The README update, resolver module, postgres installation changes, and tests directly support the pgvector version-resolution objective. No unrelated code changes are identified.

Full details: Linked Issues check

Explanation

The changes satisfy issue [#145]. They replace the hard-coded pgvector version with pool-based resolution, known-version fallback, retry handling, and environment overrides. This addresses package removal and 404 installation failures.

Full details: Docstring Coverage

Explanation

Docstring coverage is 58.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 12 functions across 3 files. (1 skipped: 1 unsupported.)

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/pgvector-version-resolve

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}