Skip to content

Add health indicator for PgVector vector store#5764

Open
iaJingda wants to merge 1 commit intospring-projects:mainfrom
iaJingda:gh-1611-pgvector-health-indicator
Open

Add health indicator for PgVector vector store#5764
iaJingda wants to merge 1 commit intospring-projects:mainfrom
iaJingda:gh-1611-pgvector-health-indicator

Conversation

@iaJingda
Copy link
Copy Markdown

@iaJingda iaJingda commented Apr 7, 2026

Summary

This PR adds a Spring Boot Actuator HealthIndicator for the PgVector vector store, addressing #1611.

Why

Spring AI vector stores can become unavailable independently from the application (e.g., database connection lost, the vector PostgreSQL extension uninstalled). Production deployments need observability into the health of these external dependencies, following Spring Boot's standard HealthIndicator pattern.

Changes

  • Added PgVectorStoreHealthIndicator that verifies the vector PostgreSQL extension is installed and reachable
  • Added PgVectorStoreHealthAutoConfiguration for conditional auto-configuration
  • Registered the new auto-configuration in AutoConfiguration.imports
  • Added optional spring-boot-health dependency in pom.xml
  • Added unit tests covering 6 scenarios

Behavior

The health indicator:

  • Calls SELECT extversion FROM pg_extension WHERE extname = 'vector'
  • Reports UP with details (vectorExtensionVersion, database) when the extension is installed
  • Reports DOWN with reason when the extension is missing
  • Reports DOWN when the query throws an exception
  • Can be disabled via management.health.pgvector.enabled=false
  • Backs off when the user provides a custom pgvectorHealthIndicator bean

Tests

Unit tests cover:

  • Health indicator registered when PgVectorStore bean is present
  • UP status when vector extension is installed (with version details)
  • DOWN status when vector extension is missing
  • DOWN status on JDBC exception
  • Not registered when management.health.pgvector.enabled=false
  • Backs off when a custom pgvectorHealthIndicator bean is provided

All 6 tests pass locally.

Notes

This is intentionally a focused, minimal-scope PR for a single vector store. If the approach is approved, I'm happy to follow up with similar health indicators for other vector stores (Redis, Elasticsearch, etc.) in separate PRs.

Related to the earlier work in #5553 (closed), which proposed a similar pattern for Qdrant and Weaviate.

Adds a Spring Boot Actuator HealthIndicator for the PgVector vector store that verifies the vector PostgreSQL extension is installed and reachable. Reports the extension version as part of the health details when UP.

The health indicator can be disabled via:

management.health.pgvector.enabled=false

Closes spring-projectsgh-1611

Signed-off-by: jiajingda <dadamonkey1@gmail.com>
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