Skip to content

Release v0.2.0

Choose a tag to compare

@oranheim oranheim released this 05 Aug 12:37
· 38 commits to master since this release

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 (including Optional and Union variants) as JSONB columns
  • Uses the new TypeInspector utility for intelligent type analysis
  • Supports model inheritance and nested type detection
  • Can be disabled for manual control when needed

Dual Processing Modes

  1. psycopg Native Adapters (Default) - High-performance JSON handling at the driver level
  2. Custom JSON Processing - Fallback mechanism with enhanced type support for UUID, datetime, date, time, Decimal, set, and frozenset

Flexible Configuration

  • New BaseRepository parameters: json_fields, auto_detect_json, and strict_json_processing
  • Database-level control via enable_json_adapters setting
  • 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.toml to follow PEP 621 standard
  • Modern dependency resolution with uv.lock

Enhanced CI/CD

  • New GitHub Actions workflows:
    • build-test.yml - Comprehensive CI testing
    • release.yml - Automated PyPI releases
    • benchmark.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.md documentation
  • 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 dict or list are 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.