pgvecto-rs Python Binding

0.2.2 verified Mon Apr 27 auth: no python

Python binding for pgvecto.rs, a vector similarity search extension for PostgreSQL. Current version 0.2.2, requires Python 3.8-3.12. Provides client and ORM integrations for vector operations in PostgreSQL.

pip install pgvecto-rs

Common errors

error ModuleNotFoundError: No module named 'pgvecto_rs' ↓

cause Package name has hyphen but import uses underscore; also may not be installed.

fix

Run 'pip install pgvecto-rs' and import as 'pgvecto_rs' (underscore).

error AttributeError: module 'pgvecto_rs' has no attribute 'SQLModelVector' ↓

cause SQLModelVector is in submodule pgvecto_rs.sqlalchemy.

fix

Use 'from pgvecto_rs.sqlalchemy import SQLModelVector'.

error psycopg2.errors.UndefinedFile: extension "vectors" is not available ↓

cause pgvecto.rs extension not installed on the PostgreSQL server, or shared library path not set.

fix

Install pgvecto.rs on the server (see docs). Then run 'CREATE EXTENSION vectors' as superuser.

Warnings

breaking The 'pgvecto_rs.client' module uses a different connection API than psycopg2. Do not use psycopg2 connection objects directly; use client.connect(). ↓

fix Use client.connect(...) with parameters, not raw psycopg2 connections.

gotcha Vector dimensions must match column definition when inserting. Use string representation like '[1,2,3]'::vector. Lists or numpy arrays are not directly accepted. ↓

fix Cast vectors to string: str([1,2,3]) or use f"'{list}'::vector".

gotcha The 'client' module is not a drop-in replacement for 'psycopg2'. It wraps a different underlying driver (Rust-based). Some psycopg2 features (e.g., connection pooling, async) may not be available. ↓

fix Check the official documentation for supported features. For connection pooling, use SQLAlchemy or another pooling library.

Imports

client
wrong
```
import pgvecto-rs
```
correct
```
from pgvecto_rs import client
```
Hyphen in package name; underscore in import

SQLModelVector

wrong

from pgvecto_rs import SQLModelVector

correct

from pgvecto_rs.sqlalchemy import SQLModelVector

Must import from submodule sqlalchemy

Vector

wrong

from pgvecto_rs import Vector

correct

from pgvecto_rs.sqlalchemy import Vector

Vector type lives in sqlalchemy submodule

Quickstart

Connect to PostgreSQL, enable pgvecto.rs extension, create a vector table, insert and query vectors.

from pgvecto_rs import client

conn = client.connect(
    host='localhost',
    port=5432,
    user='postgres',
    password=os.environ.get('PGPASSWORD', ''),
    database='vectordb'
)
conn.execute("CREATE EXTENSION IF NOT EXISTS vectors")
conn.execute("CREATE TABLE IF NOT EXISTS items (id bigserial PRIMARY KEY, embedding vector(3))")
conn.execute("INSERT INTO items (embedding) VALUES ('[1,2,3]'::vector)")
results = conn.execute("SELECT * FROM items ORDER BY embedding <-> '[3,2,1]'::vector LIMIT 5")
for row in results:
    print(row)