Fixing a pgvector CI mismatch in a FastAPI RAG backend

Xitong Shan — Sat, 22 Aug 2026 15:33:05 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup, powered by Sentry.

Project Overview

mini-agent is a public FastAPI backend for an AI support-agent demo. Its test suite covers API behavior, authentication, rate limiting, approval flows, and PostgreSQL/pgvector-backed retrieval.

The GitHub Actions workflow starts PostgreSQL and Redis service containers before running the Python test suite. The application database initialization also executes:

CREATE EXTENSION IF NOT EXISTS vector

The dependency is also visible in the DocumentChunk.embedding column, which uses pgvector's Vector type. That made the database image part of the test contract, not just incidental infrastructure.

Bug Fix or Performance Improvement

On August 12, 2026, the CI run for the preceding commit reached the test step and failed:

The workflow was using the general-purpose postgres:17-alpine service image, while the application required the pgvector extension during database initialization. The test environment therefore did not match the database capability required by the code.

The failure was specific enough to avoid a broad rewrite: the container initialized successfully, dependency installation passed, and the workflow stopped only at Run tests. That pointed to the application/database boundary rather than the GitHub Actions runner or Python installation.

The fix changed one line:

 services:
   postgres:
-    image: postgres:17-alpine
+    image: pgvector/pgvector:0.8.6-pg17

Full change: Use pgvector image in CI

The PostgreSQL major version, credentials, port mapping, health check, application environment, dependency installation, and test command all remained unchanged. This kept the patch narrow and made the CI database expose the same required extension as the application.

Code

The evidence is a direct before-and-after pair:

The preceding workflow failed at Run tests.
The one-line database-image commit triggered a new workflow.
The new run completed Run tests successfully and the overall workflow passed.

Check	Before	After
PostgreSQL service image	`postgres:17-alpine`	`pgvector/pgvector:0.8.6-pg17`
Container initialization	Passed	Passed
Dependency installation	Passed	Passed
`Run tests`	Failed	Passed
Overall workflow	Failed	Passed

No tests were disabled, no failure was ignored, and no application feature was added to make the build green.

My Improvements

The visible patch is small, but it fixes an important reliability boundary: integration tests are only meaningful when their service dependencies provide the capabilities the application actually uses.

The change:

restores the full CI test run;
makes the PostgreSQL service compatible with the repository's pgvector-backed model;
preserves PostgreSQL 17 rather than changing database versions as a side effect;
avoids installing database extensions ad hoc during every CI run;
keeps the workflow readable and reproducible with a pinned pgvector image tag.

The general lesson is to treat database extensions as explicit runtime dependencies. If application startup creates or queries extension-backed types, CI must supply that extension too. A healthy generic PostgreSQL container is not enough when the application's schema contract includes extension-defined types.

Disclosure