pgcontext_pgvector

Overview

Optional control shipped by pgcontext 0.2.0; requires pgcontext and vector.

Version

Build

You can build the RPM / DEB packages for pgcontext using pig build:

pig build pkg pgcontext         # build RPM / DEB packages

Install

You can install pgcontext directly. First, make sure the PGDG and PIGSTY repositories are added and enabled:

pig repo add pgsql -u          # Add repo and update cache

Install the extension using pig or apt/yum/dnf:

• Install
• pig
• dnf
• apt

pig install pgcontext;          # Install for current active PG version

pig ext install -y pgcontext -v 18  # PG 18
pig ext install -y pgcontext -v 17  # PG 17

dnf install -y pgcontext_18       # PG 18
dnf install -y pgcontext_17       # PG 17

apt install -y postgresql-18-pgcontext   # PG 18
apt install -y postgresql-17-pgcontext   # PG 17

Create Extension:

CREATE EXTENSION pgcontext_pgvector CASCADE;  -- requires: pgcontext, vector

Usage

Sources:

• pgContext 0.2.0 pgvector coexistence guide
• pgContext 0.2.0 pgvector migration guide
• pgcontext_pgvector control file
• pgcontext_pgvector extension SQL
• pgContext 0.2.0 release notes

pgcontext_pgvector is the optional pgContext companion bridge for serving pgContext HNSW indexes over columns owned by the pgvector extension. It does not merge the two type systems or copy application data; it adds certified casts, support functions, and operator classes while exact distance semantics remain bound to pgvector operators.

Certified Profile and Installation

Version 0.2.0 fails closed unless the database uses PostgreSQL 17, pgContext 0.2.0, and pgvector 0.8.x installed in public. Install the prerequisites and bridge explicitly:

CREATE EXTENSION vector;
CREATE EXTENSION pgcontext;
CREATE EXTENSION pgcontext_pgvector;

The reverse order of the two prerequisite extensions is also valid, but pgcontext_pgvector must come after both. Installation requires superuser privileges.

Index an Existing pgvector Column

CREATE INDEX items_embedding_pgc
    ON items USING pgcontext_hnsw
       (embedding pgcontext.vector_hnsw_pgvector_cosine_ops);

SELECT id
FROM items
ORDER BY embedding <=> $1::public.vector
LIMIT 10;

Existing pgvector-spelled SQL can use the pgContext access method. ANN candidates are resolved to live heap rows and reranked with the pgvector operator, preserving its double precision distance result semantics.

Important Objects

• pgcontext.vector_hnsw_pgvector_l2_ops, pgcontext.vector_hnsw_pgvector_ip_ops, pgcontext.vector_hnsw_pgvector_cosine_ops, and pgcontext.vector_hnsw_pgvector_l1_ops serve existing public.vector columns.
• pgcontext.sparsevec_hnsw_pgvector_cosine_ops serves certified public.sparsevec columns, subject to the documented 16,000-dimension and page-envelope limits.
• pgcontext.migration_report() inventories pgvector columns, dependencies, HNSW, and IVFFlat without requiring the bridge.
• Ownership-conversion functions provide reviewed fast or restricted-online workflows; IVFFlat is rebuilt as HNSW rather than converted in place.

Dependency and Removal Boundaries

The main pgcontext extension remains independent of pgvector. Bridge indexes depend on pgcontext_pgvector, and the bridge depends on both parent extensions, so PostgreSQL blocks removal under RESTRICT until those indexes are removed or converted.

Do not use DROP EXTENSION vector CASCADE as a migration method. Inventory arrays, views, functions, prepared sessions, expression indexes, and other application dependencies first. The bridge does not provide every pgvector helper, IVFFlat, iterative-scan GUC, parallel-build, subvector, or progress-reporting behavior.

No preload or restart is required. The bridge is a privileged compatibility surface, not a promise that all future pgContext, pgvector, PostgreSQL-major, or on-disk index combinations are compatible; rerun the certified preflight and rebuild validation when any component changes.