DEV Community

Xitong Shan
Xitong Shan

Posted on

Fixing a pgvector CI mismatch in a FastAPI RAG backend

#devchallenge #bugsmash #postgres #python

Summer Bug Smash: Clear the Lineup 🐛🛹

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. The preceding workflow failed at Run tests.
  2. The one-line database-image commit triggered a new workflow.
  3. 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

The code change, commit timestamps, and workflow outcomes are public and independently inspectable through the links above. This write-up was prepared with AI-assisted editing and was personally reviewed by the entrant before publication. No production data, customer credentials, or private incident details are included.

Top comments (0)