Skip to content

Release v0.2.0

Choose a tag to compare

View all tags
@fsecada01 fsecada01 released this 17 Feb 04:03
· 4 commits to main since this release
v0.2.0
28d7b37

v0.2.0 - Production-Ready Features

Release Date: 2026-02-16

🎉 What's New

Major Features

1. Public API Exports

  • All CRUD functions now importable from package root
  • Clean, intuitive imports: from sqlmodel_crud_utils import get_row, a_get_row
  • __version__ attribute accessible
  • 29 total exports in __all__

2. Custom Exception Hierarchy

  • SQLModelCRUDError - Base exception for all library errors
  • RecordNotFoundError - Record not found with model context
  • MultipleRecordsError - Multiple records found when one expected
  • ValidationError - Data validation failures with field details
  • BulkOperationError - Bulk operation failures with success/failure tracking
  • TransactionError - Transaction failures with operation context

3. Transaction Context Managers

  • transaction(session) - Synchronous transaction management
  • a_transaction(session) - Asynchronous transaction management
  • Auto-commit on success, auto-rollback on errors
  • Exception chain preservation for debugging

4. Audit Trail Mixins

  • AuditMixin - Automatic timestamp and user tracking
    • created_at - Auto-set on creation
    • updated_at - Auto-set on updates
    • created_by - Optional user tracking
    • updated_by - Optional user tracking
  • Timezone-aware datetime (no deprecation warnings)

5. Soft Delete Support

  • SoftDeleteMixin - Non-destructive deletion
    • is_deleted - Boolean flag for deleted records
    • deleted_at - Timestamp of deletion
    • deleted_by - Optional user tracking
    • soft_delete(user) - Mark record as deleted
    • restore() - Restore deleted record

📊 Testing & Quality

  • 47 new comprehensive tests (100% passing)
  • 96 total tests passing (existing + new)
  • 100% coverage of new features
  • Type checking passing - All type checks pass with modern Python type hints
  • Backward compatible - 100% compatibility with v0.1.0

📖 Usage Examples

Public API

# Before (v0.1.0)
from sqlmodel_crud_utils.sync import get_row, update_row
from sqlmodel_crud_utils.a_sync import get_row as a_get_row

# After (v0.2.0)
from sqlmodel_crud_utils import get_row, update_row, a_get_row

Exception Handling

from sqlmodel_crud_utils import RecordNotFoundError, get_row

try:
    success, user = get_row(id_str=999, session=session, model=User)
    if not success:
        raise RecordNotFoundError(model=User, id_value=999)
except RecordNotFoundError as e:
    print(f"Not found: {e}")

Transaction Management

from sqlmodel_crud_utils import transaction, write_row, update_row

with transaction(session) as tx:
    user = write_row(User(name="Alice"), tx)
    update_row(user.id, {"email": "alice@example.com"}, User, tx)
    # Auto-commits on success, rolls back on error

Audit Trails

from sqlmodel import SQLModel, Field
from sqlmodel_crud_utils import AuditMixin

class User(SQLModel, AuditMixin, table=True):
    id: int = Field(primary_key=True)
    name: str
    # Automatically adds: created_at, updated_at, created_by, updated_by

Soft Deletes

from sqlmodel import SQLModel, Field
from sqlmodel_crud_utils import SoftDeleteMixin

class Product(SQLModel, SoftDeleteMixin, table=True):
    id: int = Field(primary_key=True)
    name: str
    # Automatically adds: is_deleted, deleted_at, deleted_by

# Usage
product.soft_delete(user="admin")  # Mark as deleted
product.restore()  # Restore deleted record

🔄 Migration from v0.1.0

No migration needed! v0.2.0 is 100% backward compatible with v0.1.0.

All new features are opt-in:

  • Exception handling: All existing code continues to work
  • Mixins: Only when explicitly inherited
  • Transaction managers: Optional context managers
  • Public API: Both old and new import styles work

📦 Installation

pip install sqlmodel-crud-utils==0.2.0

# Or with uv
uv pip install sqlmodel-crud-utils==0.2.0

🙏 Acknowledgments

Built with:

  • Multi-model orchestration using Claude Sonnet 4.5
  • Comprehensive type checking with ty
  • Test coverage with pytest
  • SQLModel and SQLAlchemy

🔗 Resources

Full Changelog: https://github.com/fsecada01/SQLModel-CRUD-Utilities/blob/main/CHANGELOG.md

Assets 6
Loading