illuma-law/healthcheck-pgvector

Focused pgvector extension health check for Spatie's Laravel Health package.

v0.1.2 2026-04-20 18:47 UTC

Requires

• php: ^8.3
• illuminate/contracts: ^11.0||^12.0||^13.0
• illuminate/database: ^11.0||^12.0||^13.0
• illuminate/support: ^11.0||^12.0||^13.0
• laravel/framework: ^12.0||^13.0
• spatie/laravel-health: ^1.39
• spatie/laravel-package-tools: ^1.16

Requires (Dev)

• larastan/larastan: ^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^8.8
• orchestra/testbench: ^11.1.0
• pestphp/pest: ^4.0
• pestphp/pest-plugin-arch: ^4.0
• pestphp/pest-plugin-laravel: ^4.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^2.0
• phpstan/phpstan-phpunit: ^2.0
• spatie/laravel-ray: ^1.35

MIT

• illuma-law

• postgres
• health
• laravel
• pgvector
• illuma-law

README

A focused pgvector extension health check for Spatie's Laravel Health package.

This package provides a simple, direct health check to verify that the vector extension (pgvector) is properly installed and active in your PostgreSQL database. This is critical for applications that rely on pgvector for storing AI embeddings and running semantic/similarity searches.

Features

• Version Detection: Checks if the vector extension is enabled and reports the specific pgvector version installed.
• Configurable Strictness: Choose whether a missing pgvector extension should return a Warning (degraded) or a Failure (broken) status for your application.
• Query Safety: Safely handles database connection errors or missing tables, returning a failed state with the exception message instead of crashing the health check suite.

Installation

Require this package with composer:

composer require illuma-law/healthcheck-pgvector

Configuration

You can publish the config file with:

php artisan vendor:publish --tag="healthcheck-pgvector-config"

The healthcheck-pgvector.php config file allows you to define whether the check is strictly required by default.

return [
    // If true, the check will FAIL when the extension is missing.
    // If false, it will generate a WARNING instead.
    'required' => false,
];

Usage & Integration

Register the check inside your application's health service provider (e.g. AppServiceProvider or a dedicated HealthServiceProvider), alongside your other Spatie Laravel Health checks:

Basic Registration

use IllumaLaw\HealthCheckPgvector\PgvectorExtensionCheck;
use Spatie\Health\Facades\Health;

Health::checks([
    PgvectorExtensionCheck::new(),
]);

Fluent Configuration

You can override the config file's default strictness on a per-check basis using the fluent required() method.

use IllumaLaw\HealthCheckPgvector\PgvectorExtensionCheck;
use Spatie\Health\Facades\Health;

Health::checks([
    // Make the health check FAIL immediately if pgvector is missing
    PgvectorExtensionCheck::new()->required(true),
]);

Expected Result States

The check interacts with the Spatie Health dashboard and JSON endpoints using these states:

• Ok: The pgvector extension is installed. The short summary and meta data will include the exact installed version (e.g. 0.7.0).
• Warning: pgvector is missing, but required is set to false.
• Failed: pgvector is missing and required is set to true.
• Failed (Exception): The database query to pg_extension throws an exception (e.g., database connection down).

Testing

Run the test suite:

composer test

License

The MIT License (MIT). Please see License File for more information.