Overview

Postvec is an extension for fused hybrid search: it combines BM25 and semantic search in one SQL call and keeps vectors in sync with your text automatically. You can also use it to migrate vectors without re-embedding of text with direct conversion between embedding formats.

Inference runs locally inside PostgreSQL or remote on postvec-server or through hosted embedding APIs.

Qualify every call: postvec.enable(...), postvec.search(...).

Starting point	First call
A text column with no vectors	enable() creates the shadow column and queues existing rows
A column that already holds vectors	adopt() registers it and keeps the stored bytes
A stored model to replace	migrate() converts vectors in place, or re-embeds them

The bundled MiniLM model runs locally. A column can also use a hosted embedding API (OpenAI, Cohere, Amazon Bedrock, Gemini, Mistral, OpenRouter or UniVec). The key stays in the inference layer. External providers.

Requirements

PostgreSQL 16, 17 or 18. pgvector 0.8 or newer, on the same major.

Install

Host	Path
Container	Quick start local or both containers
Self-hosted cluster	Packages or Docker, then postvec setup
RDS, Aurora, Cloud SQL, Azure Flexible Server, Supabase, Neon	Managed PostgreSQL

On a self-hosted cluster:

1. Install packages or start the Docker image.
2. Run postvec setup. Expected: postvec.models lists MiniLM.
3. enable() a text column, or adopt() a populated one. Expected: a registry id. The shadow column stays NULL until the worker writes it.
4. Wait until pending_jobs = 0 in status().
5. Build an ANN index. index_mode defaults to manual.
6. Search. Hybrid by default.

Inference hosts

	Embedded (default)	postvec-server
Runs in	The PostgreSQL launcher, one thread	A separate process, multi-threaded
Source text	Stays on the database host, except columns bound to an external provider	Reaches the server that holds the model
Scale	One host	A CPU or GPU fleet
Models	postvec model ... on the database host	Dashboard or HTTP API
Managed PostgreSQL	Use postvec-server	Managed PostgreSQL

SQL, the job queue and the sync behaviour are identical in both modes. Use postvec-server for process isolation, more threads on the same VM, a fleet, or a database that cannot load the extension. When to use postvec-server.

Other features

Feature	Guide
Recursive chunking for long documents	Chunking
Typed metadata filters	Filters
Embedding templates over several columns	Templates
Queue status and dead-letter re-drive	Status, retry_dead()
Model registry and air-gapped installs	Models
An existing pgai or pg_vectorize pipeline	Coming from pgai

Storage and ANN indexes are pgvector's.

License

The extension, the CLI and their packages use the PostgreSQL License. postvec-server is source-available under the Business Source License 1.1: development, testing, personal production and one 30-day production evaluation per organization are free; organizational production use needs postvec pro at €30/month. License.