Skip to main content

sqlatypemodel

Tests Linting PyPi status PyPi Package Version Python versions Downloads MIT License

Typed JSON fields for SQLAlchemy with automatic mutation tracking

sqlatypemodel solves the "immutable JSON" problem in SQLAlchemy. It allows you to use strictly typed Python objects (Pydantic, Dataclasses, Attrs) as database columns while ensuring that every change—no matter how deep—is automatically saved.

Powered by orjson for blazing-fast performance and featuring a State-Based Architecture for universal compatibility.


📚 Documentation

ReadTheDocs

Full documentation is available in the docs/ directory:


✨ Key Features

  • 🏗️ State-Based Tracking (v0.8.0+):

    • Universal Compatibility: Works natively with unhashable objects (e.g., standard Pydantic models, eq=True Dataclasses).
    • Zero Monkey-Patching: No longer alters your class's __hash__ or __eq__ methods. Uses internal MutableState tokens for safe identity tracking.
  • ⚡ Maximum Performance (v0.8.3+ Optimized):

    • Hot Path Acceleration: Direct object.__getattribute__() calls and type dispatch tables reduce overhead by 40%+.
    • Lazy Loading: 2.1x faster DB loading and 35% less memory usage.
    • Pre-computed state eliminates repeated lookups.
    • O(1) type checks using frozenset membership for atomic types.
  • 🐢 -> 🐇 Lazy Loading:

    • Zero-cost loading: Objects loaded from the DB are raw Python dicts until you access them.
    • JIT Wrapping: Wrappers are created Just-In-Time.
    • 5.1x faster initialization compared to eager loading.
  • 🥒 Pickle & Celery Ready:

    • Full support for pickle. Pass your database models directly to Celery workers or cache them in Redis.
    • Tracking is automatically restored upon deserialization via MutableMethods.
  • 🚀 High Performance:

    • Powered by orjson: faster serialization than standard json.
    • Native Types: Supports datetime, UUID, and numpy out of the box.
    • Smart Caching: Introspection results are cached (O(1) overhead).
  • 🔄 Deep Mutation Tracking:

    • Detects changes like user.settings.tags.append("new") automatically.
    • No more flag_modified() or reassigning the whole object.

The Problem

By default, SQLAlchemy considers JSON columns immutable unless you replace the entire object.

# ❌ NOT persisted by default in SQLAlchemy
user.settings.theme = "dark"
user.settings.tags.append("new")

session.commit() # Nothing happens! Data is lost.

The Solution

With sqlatypemodel, in-place mutations are tracked automatically:

# ✅ Persisted automatically
user.settings.theme = "dark"
user.settings.tags.append("new")

session.commit() # UPDATE "users" SET settings = ...

Installation

pip install sqlatypemodel

To ensure you have orjson (recommended):

pip install sqlatypemodel[fast]

📚 Examples & Usage

We provide a comprehensive suite of ready-to-run examples in the examples/ directory:

  1. Basic Pydantic: The standard workflow for mutation tracking.

  2. Lazy Loading Benchmarks: Performance comparison between eager and lazy loading.

  3. Dataclasses: Using the safe dataclass wrapper.

  4. Attrs Support: Integration with the attrs library.

  5. Async SQLAlchemy: Integration with AsyncSession and aiosqlite.

  6. Deep Nesting: Tracking changes in lists of dictionaries of models.

  7. Pickle & Celery: Passing models to background workers.


Quick Start (Pydantic)

1. Standard Usage (MutableMixin)

Best for write-heavy workflows or when you always access the data immediately.

from typing import List
from pydantic import BaseModel, Field
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, Session
from sqlatypemodel import ModelType, MutableMixin
from sqlatypemodel.util.sqlalchemy import create_engine

# 1. Define Pydantic Model (Inherit from MutableMixin)
class UserSettings(MutableMixin, BaseModel):
    theme: str = "light"
    tags: List[str] = Field(default_factory=list)

# 2. Define Entity
class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = "users"
    id: Mapped[int] = mapped_column(primary_key=True)
    settings: Mapped[UserSettings] = mapped_column(ModelType(UserSettings))

# 3. Usage
# Use our helper to get free orjson configuration
engine = create_engine("sqlite:///")
Base.metadata.create_all(engine)

with Session(engine) as session:
    user = User(settings=UserSettings())
    session.add(user)
    session.commit()

    # Mutation works!
    user.settings.tags.append("python")
    session.commit()

2. High-Performance Usage (LazyMutableMixin)

Recommended for read-heavy, sparse-field applications. Objects are initialized "lazily". The overhead of change tracking is only paid when you actually access the attribute.

from sqlatypemodel import LazyMutableMixin

# Just swap MutableMixin -> LazyMutableMixin
class UserSettings(LazyMutableMixin, BaseModel):
    theme: str = "light"
    # ...

Performance Benchmarks (v0.8.3):

Metric Eager Lazy Improvement Notes
Initialization (per object) 593 µs 1.6 µs 376x faster Pure Python object init
DB Load (5,000 objects) 406ms 195ms 2.1x faster SQL query + deserialization
First Field Access 2.8ms 146ms 50x slower JIT wrapping overhead
Memory Usage (5k objects) 11.8MB 7.8MB 35% less Lower overhead

Key Insight: Lazy loading is exceptionally fast at initialization and reduces DB load time significantly (2.1x). Use it for large result sets where you only access a subset of data.


License

MIT

Metadata

Release files for sqlatypemodel 0.8.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for sqlatypemodel 0.8.4
File Size Uploaded Provenance Actions
sqlatypemodel-0.8.4.tar.gz 26.7 kB Without provenance Details for sqlatypemodel-0.8.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for sqlatypemodel 0.8.4
File Interpreter ABI Platform Actions
sqlatypemodel-0.8.4-py3-none-any.whl Python 3 none any Details for sqlatypemodel-0.8.4-py3-none-any.whl

Total release size: 59.7 kB

Release files / sqlatypemodel-0.8.4.tar.gz

Download URL sqlatypemodel-0.8.4.tar.gz
Size 26.7 kB
Tags Source
SHA-256 checksum
How to use checksums
974ff4f7d83daf3950b74430222856d16d56829ec0ca184ceb5e549f73427e07
BLAKE2b-256 checksum
How to use checksums
9f4f845f847049dd37978fdb8ff540e99b4799c481b6e9b9cc3df13c769225cc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Release files / sqlatypemodel-0.8.4-py3-none-any.whl

Download URL sqlatypemodel-0.8.4-py3-none-any.whl
Size 33.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2d56318eb7245c71b7ee228faf72663339502b7f94b965e2688002c50da28a25
BLAKE2b-256 checksum
How to use checksums
e37a390a970a726783d0ead8a9da8f1a8be2c2d27201bb341a4d3a405400b1f7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.7

Security for sqlatypemodel 0.8.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page