pg_turbovec

pg_turbovec : TurboQuant-compressed vector type and ANN index access method for PostgreSQL.

Overview

Packages

Source

pig build pkg pg_turbovec;		# build rpm/deb

Install

Make sure PGDG and PIGSTY repo available:

pig repo add pgsql -u   # add both repo and update cache

Install this extension with pig:

pig install pg_turbovec;		# install via package name, for the active PG version

pig install pg_turbovec -v 18;   # install for PG 18
pig install pg_turbovec -v 17;   # install for PG 17
pig install pg_turbovec -v 16;   # install for PG 16
pig install pg_turbovec -v 15;   # install for PG 15
pig install pg_turbovec -v 14;   # install for PG 14

Create this extension with:

CREATE EXTENSION pg_turbovec;

Usage

Sources:

• v2.12.0 README
• v2.12.0 changelog
• Upgrade matrix
• Control file
• Filtering guide

pg_turbovec 2.12.0 provides the turbovec.vector type and compact vector indexes with candidate reranking against the original heap vectors. Flat search scans quantized codes; IVF additionally searches selected cells. Both are approximate unless the candidate set contains every true neighbour. Upgrading any 1.x index to 2.x requires rebuilding it.

Create and Query Vectors

CREATE EXTENSION pg_turbovec;
SET search_path = public, turbovec;

CREATE TABLE items (
  id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  embedding turbovec.vector CHECK (turbovec.vector_dims(embedding) = 8)
);
INSERT INTO items (embedding) VALUES
  ('[1,2,3,4,5,6,7,8]'),
  ('[2,1,3,5,4,7,6,8]'),
  ('[8,7,6,5,4,3,2,1]');
CREATE INDEX items_embedding_idx ON items
USING turbovec (embedding turbovec.vec_cosine_ops)
WITH (bit_width = 4);

SELECT id, embedding <=> '[1,2,3,4,5,6,7,8]'::turbovec.vector AS distance
FROM items
ORDER BY embedding <=> '[1,2,3,4,5,6,7,8]'::turbovec.vector
LIMIT 3;

Indexed vectors must have a consistent dimension that is a multiple of 8; the type accepts up to 16,000 coordinates. The example uses eight-dimensional vectors so it is valid for indexing. Use turbovec.vec_cosine_ops with <=> and turbovec.vec_ip_ops with <#>; <-> and <+> also provide exact distance operators.

Choose an Index and Tune Queries

• lists = 0 is the default flat quantized scan. Candidate reranking does not guarantee exact recall for every dataset.
• WITH (lists = N) enables IVF. Train on enough representative rows, choose the cell count for the corpus, and measure recall against an exact baseline; increasing the cell count alone does not ensure faster queries.
• bit_width = 4 is the default. Two- and three-bit quantization are also available. bit_width = 1 uses centered sign binary quantization, supports IVF, and reranks from the heap; it is a different scheme from TurboQuant.
• WITH (graph = true) is deprecated. Prefer flat or IVF for new indexes and consult the upstream migration guide for an existing graph index.

Indexes and queries can run without preload, but upstream recommends adding the library to shared_preload_libraries for its tuning GUCs. Merge it with existing entries and restart PostgreSQL; do not replace other required libraries:

shared_preload_libraries = 'pg_turbovec'

SELECT count(*) FROM pg_settings WHERE name LIKE 'turbovec.%';
SET turbovec.probes = 16;
SET turbovec.search_k = 64;

The settings query must return a nonzero count. A custom dotted parameter accepted by SET is not proof that the extension’s GUC registered. Important controls are turbovec.probes, turbovec.search_k, turbovec.oversample, turbovec.iterative_scan and turbovec.cache_size_mb. Use partial indexes for stable filters or the documented allowlist/iterative-scan paths; compare filtered results with an exact baseline. Native partitions have separate indexes that must each be maintained.

Upgrade from 1.x to 2.12.0

Schedule a maintenance window and retain the heap vectors plus a verified backup. Install the matching new binaries, update the SQL extension, and restart PostgreSQL so every backend uses the new library:

ALTER EXTENSION pg_turbovec UPDATE TO '2.12.0';

The index format changed from 7 to 8 in 2.0.0. Old indexes cannot be read in place: rebuild every TurboVec index from the heap before resuming queries, including every partition’s index. In psql, generate and run the rebuild statements:

SELECT format('REINDEX INDEX %I.%I;', n.nspname, c.relname)
FROM pg_class c
JOIN pg_am a ON a.oid = c.relam
JOIN pg_namespace n ON n.oid = c.relnamespace
WHERE a.amname = 'turbovec';
\gexec

This is ordinary blocking REINDEX. If choosing concurrent rebuilding, issue each command as a separate top-level statement, outside a transaction block or DO function, and plan for old-format scans to fail until the rebuilt index is available. Do not treat the SQL extension update alone as a completed 1.x migration.

The 2.10.2-to-2.10.3 patch preserves format 8 and does not itself require reindexing. Earlier transitions still need the actions in the upstream upgrade matrix. An already corrupted index needs repair even when a patch preserves its format; turbovec.turbovec_check(regclass) reports detected corruption and a reason.

Compatibility and Maintenance

The control file fixes objects in schema turbovec, sets superuser = false, and is not relocatable. Upstream covers PostgreSQL 13–18 and labels PostgreSQL 19 experimental in this release; current Pigsty packages cover 14–18. Binary replacement, tuning preload and major-format migration have separate restart/rebuild requirements. Version 2.10.3 parallelizes cold-backend code repacking; it does not change existing index bytes. Budget index-build memory, temporary space, WAL and vacuum work from the actual corpus, rather than treating upstream benchmark numbers as guarantees.

2.11.0 Upgrade

Version 2.11.0 adopts staged 2/4-bit search on eligible hardware and large indexes; the approximate candidate set can change. It also fixes concurrent-write index corruption and per-scan memory leaks present in 2.10.3 and earlier. When upgrading a healthy format-8 index from 2.x, install matching files, update the extension and restart: the release changes neither SQL surface nor wire format and does not require routine REINDEX. Existing corruption still requires repair; this does not change the mandatory rebuild for 1.x indexes.

Distance Rounding in 2.12.0

Vectorized exact-distance kernels change rounding for vector and halfvec inputs with eight or more dimensions. Very close neighbors can change order or cross a distance threshold; sparsevec operators are unchanged. Format 8 and existing index bytes are unchanged: update the SQL extension and reconnect or restart to load the new library, without a routine index rebuild.

Expression indexes, partial-index predicates, stored generated columns and materialized views may retain older rounded results. Rebuild indexes, refresh views and recompute stored derived values if exact agreement with new calculations matters. Existing corruption still needs repair, and all 1.x indexes still require rebuilding. IVF indexes created empty or truncated do not train cells; load data and follow the upstream rebuild procedure.