Repository navigation
Release v0.2.0
Release Notes - v0.2.0
π New Features
Comprehensive PostgreSQL JSONB Support
This release introduces robust, production-ready support for PostgreSQL's JSONB data type with seamless Pydantic model integration.
Automatic JSON Field Detection
- Automatically detects
dict,list, and complex types (includingOptionalandUnionvariants) as JSONB columns - Uses the new
TypeInspectorutility for intelligent type analysis - Supports model inheritance and nested type detection
- Can be disabled for manual control when needed
Dual Processing Modes
- psycopg Native Adapters (Default) - High-performance JSON handling at the driver level
- Custom JSON Processing - Fallback mechanism with enhanced type support for UUID, datetime, date, time, Decimal, set, and frozenset
Flexible Configuration
- New
BaseRepositoryparameters:json_fields,auto_detect_json, andstrict_json_processing - Database-level control via
enable_json_adapterssetting - Support for both strict and lenient JSON processing modes
Enhanced Error Handling
- New specialized exceptions:
JSONProcessingError,JSONSerializationError,JSONDeserializationError - Comprehensive error messages for debugging
- Protection against JSON injection and malformed data
Real-World Examples
- Production-ready JSONB usage patterns
- Complex nested structure handling
- PostgreSQL JSONB operators and querying techniques
- Transaction support with JSONB fields
- Performance optimization guidance
π§ Development Tooling Modernization
Migration to Hatch and uv
- Replaced Poetry with Hatch for building and uv for dependency management
- Updated
pyproject.tomlto follow PEP 621 standard - Modern dependency resolution with
uv.lock
Enhanced CI/CD
- New GitHub Actions workflows:
build-test.yml- Comprehensive CI testingrelease.yml- Automated PyPI releasesbenchmark.yml- Performance regression testing
- Integrated Ruff for fast, comprehensive linting and formatting
- Automated dependency updates via Renovate
π Performance Testing
- Comprehensive JSONB performance benchmarks
- Memory usage analysis tools
- Comparison metrics for JSONB vs traditional columns
- Bulk operation performance testing
π Documentation
- Dedicated
jsonb_support.mddocumentation - Multiple real-world JSONB examples
- Migration guides for existing projects
- Best practices for production use
ποΈ Architecture Improvements
- Introduced factory pattern to resolve circular dependencies
- Better separation of concerns between Database and TransactionManager
- Improved type hints with TYPE_CHECKING imports
π Security Enhancements
- SQL injection prevention using SQL identifiers for table names
- JSON injection protection in custom processing mode
π§ͺ Testing Infrastructure
- Reorganized test structure for better organization
- Added comprehensive test utilities for JSONB schema management
- Edge case testing for circular references, Unicode, and special numeric values
π Quick Start with JSONB
from psycopg_toolkit import BaseRepository
from pydantic import BaseModel
class UserProfile(BaseModel):
id: int
name: str
settings: dict # Automatically stored as JSONB
tags: list[str] # Automatically stored as JSONB
class UserRepository(BaseRepository[UserProfile, int]):
def __init__(self, db_connection):
super().__init__(
db_connection=db_connection,
table_name="user_profiles",
model_class=UserProfile,
primary_key="id"
)
# That's it! Your dict and list fields are now JSONB columnsπ Migration Notes
While this release includes some breaking changes, sensible defaults minimize disruption:
- Python 3.11+ is now required (previously 3.9+)
- JSON adapters are enabled by default for better performance
- Fields typed as
dictorlistare automatically treated as JSONB
For existing projects wanting to maintain previous behavior:
# Disable automatic JSON handling
settings = DatabaseSettings(..., enable_json_adapters=False)
repo = BaseRepository(..., auto_detect_json=False)See the full migration guide in the documentation for detailed instructions.