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](https://github.com/pgvector/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](PGVECTOR.md) for the full SQL API, index parameters, and usage guide. ## Benchmark Results
In-Memory HNSW Throughput (QPS): pgvector vs pgvectorfast Larger-Than-Memory HNSW Throughput (QPS): pgvector vs pgvectorfast
IVFFlat Median Latency (ms): pgvector vs pgvectorfast PostgreSQL Analytical Scan and Join Speedup Across Row Sizes
See [Detailed Benchmark Results](BENCHMARKS.md) 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*](https://arxiv.org/abs/2604.00423)), 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: ```sh 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 `-pg18` on release tags. To build the image locally: ```sh 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](https://wiki.postgresql.org/wiki/Apt). 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](#docker) or [build from source](#build-and-install-from-source) against a non-LTO PostgreSQL build.) 1. Ensure the [PostgreSQL APT repository (PGDG)](https://wiki.postgresql.org/wiki/Apt) 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: ```sh 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 ``` 3. Continue with [Quick Start](#quick-start) to preload `vectorfast` in `postgresql.conf` and activate Calico. ### PGXN Install from [PGXN](https://pgxn.org/dist/pgvectorfast) 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: ```sh 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`: ```sh pgxn install --sudo --pg_config /path/to/pg_config pgvectorfast ``` Continue with [Quick Start](#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 ```sh 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`: ```sh 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: ```ini shared_preload_libraries = 'vectorfast' ``` 2. Create the extensions and activate the Calico buffer pool (as superuser, outside a transaction block): ```sql 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 ``` 3. Create an HNSW index and run similarity queries using standard pgvector SQL: ```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](examples/getting-started.sql) and the full [pgvector Documentation](PGVECTOR.md) 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} } ```