Installation

pgContext 0.3 supports PostgreSQL 17 and 18. Extension binaries, development headers, pg_config, and the running server must all use the same major version. Installing a build into a different major is unsupported.

CREATE EXTENSION pgcontext must be run by a PostgreSQL superuser because pgContext installs custom access methods. Application roles do not need superuser privileges to use granted pgContext APIs. Version 0.3.0 is a clean-install baseline and has no 0.1/0.2 extension update script; see the release notes.

Installation Methods

Method Host Builds locally Availability
GHCR image Docker on Linux, macOS, or Windows No With the v0.3.0 release
Manual source Linux/macOS, or Windows through WSL2 Yes From the checkout or source archive
Local Compose playground Docker on Linux, macOS, or Windows Yes From the checkout
PGXN Linux/macOS source hosts Yes Available for 0.3.0
Homebrew macOS with Homebrew PostgreSQL 17 Yes Available from the Evokoa tap

Shell scripts target Bash. On Windows, use Docker Desktop with WSL2 and run them inside WSL2; native PowerShell and Command Prompt are not supported build shells. The image itself supports linux/amd64 and linux/arm64.

Prebuilt Docker image

The prebuilt images for this release use the v0.3.0 tag. Replace 17 with 18 to select the other supported server major:

docker pull ghcr.io/evokoa/pgcontext:pg17-v0.3.0
docker run -d --rm \
  --name pgcontext \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=pgcontext \
  -p 5432:5432 \
  ghcr.io/evokoa/pgcontext:pg17-v0.3.0

Verify PostgreSQL, the extension, dense HNSW, and metadata filtering:

docker exec pgcontext psql -U postgres -d pgcontext \
  -c 'SHOW server_version_num' \
  -c "SELECT extversion FROM pg_extension WHERE extname = 'pgcontext';"
docker exec -i pgcontext psql -U postgres -d pgcontext -v ON_ERROR_STOP=1 \
  < playground/demo.sql

Use the immutable manifest digest from the published release for controlled deployments. Every major has immutable pgMAJOR-v0.3.0 and pgMAJOR-0.3.0 aliases plus a rolling pgMAJOR alias. PostgreSQL 17 also owns the unqualified immutable version aliases and rolling latest alias.

Cleanup:

docker stop pgcontext

PGXN source installation

pgContext 0.3.0 is available from PGXN.

Prerequisites:

  • Rust 1.96.0;
  • cargo-pgrx 0.19.1;
  • PostgreSQL 17 or 18 server development headers and pg_config;
  • a C linker and ordinary build tools;
  • pgxnclient for the pgxn install command.
cargo install cargo-pgrx --version 0.19.1 --locked
cargo pgrx init --pg17="$(command -v pg_config)"
pgxn install pgContext
psql -d postgres -c 'CREATE EXTENSION pgcontext;'

Replace --pg17 with --pg18 when the selected pg_config belongs to PostgreSQL 18. pgContext is the distribution name; pgcontext is the extension name.

Homebrew

The Evokoa Homebrew tap builds pgContext 0.3.0 against Homebrew postgresql@17 and installs the PostgreSQL extension files:

brew update
brew install Evokoa/tap/pgcontext
brew services start postgresql@17
psql -X -v ON_ERROR_STOP=1 -d postgres \
  -c 'CREATE EXTENSION IF NOT EXISTS pgcontext;'

The formula does not install a standalone pgcontext shell command. Run CREATE EXTENSION in each database that should use pgContext.

Manual source build

Select the exact supported PostgreSQL installation when several versions coexist (this example uses PostgreSQL 17):

export PG_CONFIG=/usr/lib/postgresql/17/bin/pg_config
cargo install cargo-pgrx --version 0.19.1 --locked
cargo pgrx init --pg17="${PG_CONFIG}"
make install PG_CONFIG="${PG_CONFIG}"
psql -d postgres -c 'CREATE EXTENSION pgcontext;'

The final install may need filesystem privileges for PostgreSQL’s extension directories. Preserve PG_CONFIG if privilege escalation is required; do not install into a different PostgreSQL major.

Local Compose playground

git clone https://github.com/evokoa/pgcontext.git
cd pgcontext
scripts/quickstart.sh         # build, start, and run the demo
scripts/quickstart.sh setup   # start without demo data
scripts/quickstart.sh psql    # interactive prompt
scripts/quickstart.sh clean   # remove container and volume

The Compose password is development-only. Do not expose this configuration to an untrusted network.

Uninstall

Remove the extension from each database before deleting installed files, and drop dependent objects only after review:

SELECT pgcontext.drop_collection('collection_name');  -- once per collection
-- Drop dependent application tables or vector columns only after review.
DROP EXTENSION pgcontext;

Then remove the installed files with the method you installed by: make uninstall PG_CONFIG=... for a source build, or removing the container and volume for Docker (scripts/quickstart.sh clean).

Common failures

  • postgres.h: No such file or directory: install the matching PostgreSQL server development headers and confirm pg_config --includedir-server.
  • pg_config reports the wrong major: select the matching binary explicitly.
  • cargo pgrx cannot find the selected major: rerun cargo pgrx init --pgMAJOR=....
  • permission denied during install: use the filesystem privilege model for that PostgreSQL installation while preserving PG_CONFIG.
  • image tag not found or PGXN distribution missing: these artifacts are published with the v0.3.0 release; until then, use local Compose or a manual source build.
  • extension cannot be dropped: identify dependent vector columns/tables and remove them deliberately; do not use CASCADE without review.

More diagnosis is in Troubleshooting. Backup and rebuild procedures are in Operations.