Build Guide

Requirements

  • Linux x86-64
  • GCC 11+
  • Git
  • curl
  • OpenMP (libgomp, included with GCC)

Setup

Edit config before running any scripts. At minimum set:

  • PGSQL_INSTALL_DIR — PostgreSQL installation path (or set PG_CONFIG directly to skip building PostgreSQL)

All other paths default to subdirectories relative to the config file location.

Steps

1. PostgreSQL

Skip if PostgreSQL is already installed. Set PG_CONFIG in config to point to the existing pg_config binary.

Otherwise:

./install_postgres.sh

2. SVS

./build_svs.sh

Downloads the prebuilt SVS C API release (SVS_TAG in config) and extracts it to SVS_INSTALL_DIR.

3. Vanilla pgvector

./build_pgvector_vanilla.sh

Builds and installs stock pgvector into the PostgreSQL installation. This provides the vector and halfvec types that the svs extension depends on.

If PGV_VANILLA_DIR already contains pgvector source, the clone step is skipped.

4. svs extension

./build_svs_extension.sh

Builds and installs the svs extension into the PostgreSQL installation.

If SVS_EXT_REPO is set in config, the extension source is cloned from that repository. Otherwise the script builds from the source tree at SVS_EXT_DIR (which defaults to the repository root two levels above this directory).

All-in-one

./build_all.sh

Runs all steps in order. Skips install_postgres.sh if PG_CONFIG already points to an existing binary.

Required PostgreSQL settings

Add these to postgresql.conf and restart the server:

shared_preload_libraries = 'svs'
wal_level = logical
max_replication_slots = 10

wal_level = logical is required. Without it the launcher stops at startup and no worker starts. The extension creates one logical replication slot for each Vamana index. Set max_replication_slots to the number of Vamana indexes plus the slots other features use (for example physical replicas), and keep some spare. The default of 10 allows about 10 indexes in the whole cluster.

pgvector must be installed. In each database that hosts Vamana indexes, run CREATE EXTENSION vector; before CREATE EXTENSION svs;.

Then enroll each database that hosts Vamana indexes. The vamana_databases table exists only in a database where CREATE EXTENSION svs has run. First create the extensions in the launcher database (svs.launcher_database, default postgres):

CREATE EXTENSION vector;
CREATE EXTENSION svs;

Then run this in the launcher database:

CREATE DATABASE mydb;
INSERT INTO vamana_databases (datname) VALUES ('mydb');

See the user guide for details.