Repository navigation
Release Notes - v0.3.0
π Native pgvector Support
This release adds native support for PostgreSQL's pgvector extension with automatic vector field detection, following the same pattern as our existing JSONB support.
β¨ New Features
pgvector Integration
- Automatic vector field detection - Auto-detects
list[float]type hints as pgvector columns - Lazy async adapter registration - Uses
register_vector_async()for proper async handling - Graceful degradation - Works seamlessly even if pgvector package is not installed
- Per-connection registration - Properly handles connection pooling
- Type-safe operations - Full type safety with
list[float]<-> PostgreSQLvector
Repository Parameters
auto_detect_vector(default: True) - Automatically detect vector fields from type hintsvector_fields- Explicitly specify vector field names (overrides auto-detection)- Vector fields automatically excluded from JSON processing
Usage Example
from pydantic import BaseModel
from uuid import UUID
class DocumentEmbedding(BaseModel):
id: UUID
embedding: list[float] # Auto-detected as vector!
metadata: dict[str, Any]
class EmbeddingRepository(BaseRepository[DocumentEmbedding, UUID]):
def __init__(self, db_connection):
super().__init__(
db_connection=db_connection,
table_name="embeddings",
model_class=DocumentEmbedding,
primary_key="id",
# auto_detect_vector=True is default
)
# Just works - no manual parsing needed!
doc = DocumentEmbedding(
id=uuid4(),
embedding=[0.1] * 384,
metadata={"model": "all-MiniLM-L6-v2"}
)
created = await repo.create(doc)
assert isinstance(created.embedding, list) # β
Returns as list[float]π§ͺ Testing Improvements
New Tests
- 12 unit tests - Vector field detection and type inspection
- 4 integration tests - Full CRUD operations with pgvector
- 227 total tests - All passing with zero regressions
Test Organization
- Reorganized tests into proper subdirectories:
tests/unit/- Unit tests (mocked, no database)tests/integration/- Integration tests (real PostgreSQL)tests/performance/- Performance benchmarks
- Updated testcontainers to use
pgvector/pgvector:pg17 - Added float32 precision handling (pgvector uses float32, Python uses float64)
π¦ Dependencies
- Optional dependency:
pgvector>=0.4.1invectordependency group - Install with:
pip install psycopg-toolkit[vector] - Graceful degradation if not installed
π Documentation
- β
Updated
CLAUDE.mdwith pgvector support details - β
Updated
README.mdwith pgvector feature - β Added comprehensive usage examples
- β Documented vector field configuration options
- β Added pgvector support components section
π οΈ Code Quality
- Fixed all ruff linting issues (SIM102, B905, SIM222)
- Applied consistent code formatting
- Added comprehensive async testing guide to README
- Improved test organization and structure
π Statistics
+681 lines added
-388 lines removed
18 files changed
Core implementation:
- src/psycopg_toolkit/repositories/base.py (+72 lines)
- src/psycopg_toolkit/utils/type_inspector.py (+102 lines)
New tests:
- tests/integration/test_pgvector.py (119 lines, 4 tests)
- tests/unit/test_type_inspector.py (+174 lines, 12 tests)
π§ Technical Details
Type Detection (TypeInspector)
detect_vector_fields()- Detectslist[float]fields- Supports
Optional[list[float]]andlist[float] | None - Handles legacy
typing.List[float]syntax - Excludes vector fields from JSON processing
Adapter Registration (BaseRepository)
- Lazy registration on first database operation
- Uses async variant
register_vector_async() - Per-connection registration (not global)
- Logs helpful warnings if pgvector not installed
Float Precision
- pgvector uses float32 (4 bytes per dimension)
- Python uses float64 (8 bytes)
- Tests use approximate comparison with tolerance of 0.001
π Migration Guide
No breaking changes! Existing code continues to work without modifications.
To use pgvector support:
- Install pgvector:
pip install pgvector>=0.4.1 - Enable pgvector extension in PostgreSQL:
CREATE EXTENSION vector; - Use
list[float]type hints in your Pydantic models - Vector fields are automatically detected and handled!
π Credits
Feature implemented following the AI instruction specification and integrated following the existing JSONB adapter pattern for consistency.
Full Changelog: v0.2.2...v0.3.0