An HNSW index can exist and still have the wrong configuration for a retrieval workload. Changing its dimensions, distance metric or filtered population also creates an operational problem: build the replacement, verify it, publish it and retire the correct predecessor.

I built pgvector-index-manager to make that lifecycle explicit and repeatable. It is an open-source Go CLI for teams running pgvector in PostgreSQL.

A collection of index-creation scripts leaves important decisions scattered across deployment steps. Which configuration owns this index? Is the replacement structurally correct? What happens if the process restarts during the grace period? Can a second configuration accidentally retire an index used by another population?

I separated the workflow into status, plan and apply commands. Engineers can inspect the current catalog and review proposed changes before allowing mutations. A configuration defines the vector identity, distance metric, HNSW parameters and optional population filters. Equality and IN filters are supported through structured configuration; identifiers and values are handled separately.

The reconciler holds a PostgreSQL advisory lock throughout the mutation sequence. It builds a replacement concurrently under a temporary name, then checks its health and catalog structure before publishing it. Checks cover the vector source, dimensions, operator class, parameters, key layout and population predicate. The published index is checked again.

Ownership is part of the design. Each configuration manages a named index family. Structured metadata records ownership, the specification hash and the verified expression/predicate fingerprint. A configuration cannot retire another managed family's indexes, and conflicting unowned indexes are protected by default.

I also made retirement recoverable. The old index stores an absolute UTC grace deadline, allowing a restarted process to respect the remaining delay before concurrent removal. Reports redact connection strings and omit or generalize target details by default.

The tool provides a reviewable sequence from catalog inspection to replacement and JSON reporting. It packages operational safeguards into one reusable workflow for vector-search infrastructure.

A Docker Compose demo seeds 10,000 synthetic documents with 128-dimensional vectors so engineers can explore status, apply and status again in an ephemeral database. The repository includes configuration examples, operational guidance and an Apache-2.0 license.

Project: https://nikocodes.com/software/pgvector-index-manager/ Source: https://github.com/lame13/pgvector-index-manager