Contents

• pgvectorfast
  • Benchmark Results
  • How It Works
  • Installation
    • Docker
    • APT (Debian)
    • PGXN
    • Build and Install from Source
  • Quick Start
  • Configuration
  • Cite pgvectorfast

pgvectorfast

pgvectorfast is a high-performance drop-in enhancement for pgvector that accelerates vector similarity search and analytical queries in PostgreSQL using a fast shared buffer pool.

Based on pgvector, pgvectorfast is a standard PostgreSQL extension on unmodified PostgreSQL 18 and 19 servers for fast vector similarity search. It preserves complete SQL and on-disk compatibility with all pgvector data types (vector, halfvec, bit, sparsevec), distance operators, and index types (hnsw, ivfflat). See the pgvector Documentation for the full SQL API, index parameters, and usage guide.

Benchmark Results

See Detailed Benchmark Results for latency breakdowns, ablation tables, and experimental configurations.

How It Works

PostgreSQL’s default buffer manager translates every page reference through a partitioned shared hash table and acquires atomic pins and buffer content locks on every page read. Across vector index lookups and analytical scans/joins—and especially during HNSW graph traversal, which performs thousands of irregular neighbor lookups per query—page translation, pin/unpin atomic traffic, and synchronous random I/O become major bottlenecks.

pgvectorfast replaces PostgreSQL’s shared buffer manager with the Calico buffer pool (Making Array-Based Translation Practical for Modern, High-Performance Buffer Management), combining three techniques:

1. Array-Based Page Translation & Path Caching: Replaces PostgreSQL’s shared buffer lookup hash table and partition locks on hot paths with two-level direct array indexing backed by lazily allocated virtual memory regions, paired with a per-backend relation prefix cache (~100% hit rate on HNSW indexes).
2. Lock-Free Optimistic Reads (calico.optimistic_reads): Encodes lock and version state in each 64-bit translation entry so HNSW traversal reads neighbor vectors and computes L2 distances speculatively without atomic pin/unpin operations or content locks, falling back seamlessly to pinned reads whenever concurrent writes or evictions occur.
3. Workload-Aware Group Prefetch (hnsw.enable_prefetch): Batches neighbor page lookups at each HNSW graph hop to issue parallel translation loads and targeted CPU cache prefetches (__builtin_prefetch) for resident pages (memory-level parallelism), alongside batched asynchronous reads via PostgreSQL AIO / io_uring for non-resident pages (I/O-level parallelism).

Installation

Docker

Pull and run a ready-to-use image for x86-64 (linux/amd64) with PostgreSQL 18, matching debug symbols (postgresql-18-dbgsym), and shared_preload_libraries = 'vectorfast' preconfigured:

docker run -d \
  --name pgvectorfast \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -p 5432:5432 \
  zxjcarrot/pgvectorfast:pg18

Available tags: pg18 / latest (postgres:18-trixie), pg18-trixie, pg18-bookworm, and <version>-pg18 on release tags.

To build the image locally:

docker build --build-arg PG_MAJOR=18 -t pgvectorfast .

APT (Debian)

Prebuilt postgresql-18-pgvectorfast packages for Linux x86-64 (amd64) are published for Debian 12 (bookworm) and Debian 13 (trixie) against the PostgreSQL PGDG APT repository. They declare Conflicts/Replaces/Provides for postgresql-18-pgvector and depend on matching postgresql-18-dbgsym symbols. (Ubuntu PGDG packages compile PostgreSQL with -flto=auto, which Calico rejects at startup because LTO inlines internal buffer-manager routines; on Ubuntu, use the Docker image or build from source against a non-LTO PostgreSQL build.)

1. Ensure the PostgreSQL APT repository (PGDG) is enabled (for example via postgresql-common / /usr/share/postgresql-common/pgdg/apt.postgresql.org.sh).
2. Add the pgvectorfast APT signing key and repository, then install:

sudo install -d -m 0755 /etc/apt/keyrings
curl -fsSL https://mitdbg.github.io/pgvectorfast/pgvectorfast.asc | sudo tee /etc/apt/keyrings/pgvectorfast.asc >/dev/null
echo "deb [signed-by=/etc/apt/keyrings/pgvectorfast.asc] https://mitdbg.github.io/pgvectorfast $(. /etc/os-release && echo "$VERSION_CODENAME") main" | sudo tee /etc/apt/sources.list.d/pgvectorfast.list
sudo apt-get update
sudo apt-get install -y postgresql-18-pgvectorfast

1. Continue with Quick Start to preload vectorfast in postgresql.conf and activate Calico.

PGXN

Install from PGXN using pgxnclient. Because PGXN compiles from source against your PostgreSQL installation, first ensure you have PostgreSQL 18 or 19 development headers (pg_config), non-LTO server symbols (such as postgresql-18-dbgsym on Debian PGDG, or an unstripped source build), libcapstone-dev (or Python pip), a C compiler, and GNU Make:

sudo apt-get update
sudo apt-get install -y pgxnclient build-essential libcapstone-dev postgresql-server-dev-18 postgresql-18-dbgsym
sudo pgxn install pgvectorfast

If your target pg_config is not first on PATH (or you build as an unprivileged user), pass --pg_config and --sudo:

pgxn install --sudo --pg_config /path/to/pg_config pgvectorfast

Continue with Quick Start to preload vectorfast in postgresql.conf and activate Calico.

Build and Install from Source

Prerequisites

• Linux x86-64
• PostgreSQL 18 or 19 with server development headers (pg_config) and non-LTO server symbols: either an unstripped source build or a packaged build with matching debug symbols installed (e.g. postgresql-18-dbgsym)
• C compiler (GCC or Clang) and GNU Make
• Capstone (libcapstone-dev 4.x/5.x from system packages, or automatically bootstrapped as capstone==5.0.6 into ~/.cache/pgvectorfast/python-deps via Python pip during make; override with CAPSTONE_PREFIX=/path/to/capstone; must remain available at runtime)

Build and Install

git clone https://github.com/mitdbg/pgvectorfast.git
cd pgvectorfast
make
make install # may need sudo

If your target PostgreSQL installation is not first on PATH, pass PG_CONFIG:

make PG_CONFIG=/path/to/pg_config
make PG_CONFIG=/path/to/pg_config install

Quick Start

1. Add vectorfast to shared_preload_libraries in postgresql.conf and restart PostgreSQL:

shared_preload_libraries = 'vectorfast'

1. Create the extensions and activate the Calico buffer pool (as superuser, outside a transaction block):

CREATE EXTENSION vector;   -- pgvector types, operators, and indexes
CREATE EXTENSION calico;   -- Calico shared buffer pool management

SELECT calico.status();    -- 'stock' before activation
CALL calico.activate();    -- switches PostgreSQL's shared buffer pool to Calico
SELECT * FROM calico.pool; -- inspect pool status, mappings, and statistics

1. Create an HNSW index and run similarity queries using standard pgvector SQL:

CREATE TABLE items (id bigserial PRIMARY KEY, embedding vector(128));
CREATE INDEX ON items USING hnsw (embedding vector_l2_ops);
SELECT * FROM items ORDER BY embedding <-> '[...]' LIMIT 10;

Activation switches PostgreSQL’s entire shared buffer pool across all databases (covering both pgvector indexes and ordinary heap/B-tree relations) and remains active until the server restarts. Without shared_preload_libraries, CREATE EXTENSION vector continues to work using PostgreSQL’s standard buffer manager.

See the runnable getting-started example and the full pgvector Documentation for all vector types, distance operators, iterative scans, and indexing options.

Configuration

Parameter	Context	Default	Description
calico.optimistic_reads	Session / User	on	Enables lock-free optimistic tuple reads during HNSW traversal (vector_l2_ops).
hnsw.enable_prefetch	Session / User	on	Enables batched neighbor group prefetching (CPU prefetch + async read batching) during HNSW search.

Cite pgvectorfast

If you are using pgvectorfast, please cite our work as follows bibtex @misc{zhou2026calico, title = {Making Array-Based Translation Practical for Modern, High-Performance Buffer Management}, author = {Xinjing Zhou and Jinming Hu and Andrew Pavlo and Michael Stonebraker}, year = {2026}, eprint = {2604.00423}, archivePrefix = {arXiv}, primaryClass = {cs.DB}, url = {https://arxiv.org/abs/2604.00423} }