# 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](release_notes.md#compatibility-and-migration).

## 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:

```sh
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:

```sh
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:

```sh
docker stop pgcontext
```

## PGXN source installation

pgContext 0.3.0 is available from
[PGXN](https://pgxn.org/dist/pgcontext/0.3.0/).

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.

```sh
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](https://github.com/Evokoa/homebrew-tap) builds
pgContext 0.3.0 against Homebrew `postgresql@17` and installs the PostgreSQL
extension files:

```sh
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):

```sh
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

```sh
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:

```sql
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](troubleshooting.md). Backup and rebuild
procedures are in [Operations](operations.md).
