Build from source

Build from source for a development tree. Persistent deployments should use packages. Keep a source install on its own prefix, separate from package files.

Prerequisites

• Rust 1.96 or newer
• cargo-pgrx 0.18.1
• protoc
• PostgreSQL server-development headers for the target major
• pgvector >= 0.8 built against the same pg_config

rustc --version
cargo pgrx --version
protoc --version
/usr/lib/postgresql/18/bin/pg_config --version

Build

The extension is outside the Cargo workspace. The CLI remains a workspace member.

cd postvec
cargo pgrx package \
  --no-default-features \
  --features pg18,embedded \
  --pg-config /usr/lib/postgresql/18/bin/pg_config

cd ..
cargo build --release -p postvec-cli

Staged extension: postvec/target/release/postvec-pgNN/. CLI: target/release/postvec. The build stays inside the repository.

Install into a pgrx cluster

cd postvec
cargo pgrx install --release \
  --no-default-features \
  --features pg18,embedded \
  --pg-config /path/to/development/postgres/bin/pg_config

Replace pg18 with pg16 or pg17 to match that development cluster.

Install into a system PGDG tree

These files have no package owner. Every copied path needs a record so it can be removed later.

export PV_STAGE=postvec/target/release/postvec-pg18

sudo install -m 0755 \
  "$PV_STAGE/usr/lib/postgresql/18/lib/postvec.so" \
  /usr/lib/postgresql/18/lib/postvec.so
sudo install -m 0644 \
  "$PV_STAGE/usr/share/postgresql/18/extension/postvec.control" \
  "$PV_STAGE/usr/share/postgresql/18/extension/postvec--0.5.0.sql" \
  /usr/share/postgresql/18/extension/

sudo install -m 0755 target/release/postvec /usr/local/bin/postvec

Embedded engine root

A source build has no ONNX Runtime and no weights. Install the engine-asset packages, reuse an existing engine root or copy the packaging payloads:

cd packaging/postvec
scripts/build-onnxruntime-bundle.sh --arch amd64
# The bundled model comes from the postvec model registry's public channel,
# pulled by the postvec CLI built above.
scripts/build-model-bundle.sh

sudo install -d -m 0755 /opt/postvec
sudo cp -a build/payload-amd64/opt/postvec/libs \
  /opt/postvec/
sudo cp -a build/payload-common/opt/postvec/models \
  /opt/postvec/

Manually copied models are operator-owned. Remove them by hand.

Build postvec-server

postvec-server is an ordinary workspace member, so it needs neither pgrx nor PostgreSQL headers. It runs in its own process, so a model fault stays out of PostgreSQL and inference can use several threads on the same VM:

cargo build --release -p postvec-server
sudo install -m 0755 target/release/postvec-server /usr/local/bin/

It still needs ONNX Runtime and at least one model under its --root, which is the same engine root described above. Build postvec-server from source covers TLS, the first start and the dashboard.

Development rebuild sequence

1. Run cargo pgrx package again after a change to the extension. It builds the library, regenerates the SQL and stages both under postvec/target/release/postvec-pgNN/.
2. Stop PostgreSQL before you replace the preloaded library. The server releases postvec.so on shutdown, so step 3 writes to a file no running process holds.
3. Copy the staged files into the cluster's library and extension directories. The next start then reads the new library, control file and SQL.
4. Recreate a development database if the generated SQL for the same version changed. CREATE EXTENSION postvec then installs the current SQL.

A new .so leaves SQL already in a database as it is. A new extension version needs upgrade SQL plus ALTER EXTENSION postvec UPDATE in the same window as the restart. Upgrade.

Rollback (files only)

Stop PostgreSQL first. With dpkg -S or rpm -qf, skip any path a package still owns. Remove only recorded files, then restore any previous manual installation while the cluster remains stopped.

Cluster configuration follows file installation. If setup already ran, finish uninstallation before deleting files.