Installation

pgContext V1 supports PostgreSQL 17 exclusively. Extension binaries, development headers, pg_config, and the running server must all use the same major version. Installing a PG17 build into another major is unsupported.

Installation Methods

Method Host Builds locally Availability
GHCR image Docker on Linux, macOS, or Windows No With the v0.1.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 Future update
Homebrew macOS with Homebrew PostgreSQL 17 Yes Future update

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 image is published with the v0.1.0 release:

docker pull ghcr.io/evokoa/pgcontext:pg17-v0.1.0
docker run -d --rm \
  --name pgcontext \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=pgcontext \
  -p 5432:5432 \
  ghcr.io/evokoa/pgcontext:pg17-v0.1.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. pg17-v0.1.0, pg17-0.1.0, v0.1.0, and 0.1.0 are immutable version aliases. Only pg17 and latest are rolling convenience aliases.

Cleanup:

docker stop pgcontext

PGXN source installation

Coming soon. PGXN publication is a future update. Until it is available, use the Docker image, the manual source build below, or the local Compose playground.

Prerequisites:

  • Rust 1.96.0;
  • cargo-pgrx 0.19.1;
  • PostgreSQL 17 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;'

pgContext is the distribution name; pgcontext is the extension name.

Homebrew (coming soon)

Coming soon. A Homebrew formula — brew install pgcontext from the Evokoa tap, building against postgresql@17 — will be added in a future update.

Manual source build

Select the exact PG17 installation when several PostgreSQL versions coexist:

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 PostgreSQL 17 server development headers and confirm pg_config --includedir-server.
  • pg_config must report PostgreSQL 17: select the PG17 binary explicitly.
  • cargo pgrx cannot find PG17: rerun cargo pgrx init --pg17=....
  • 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.1.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.