sqlatypemodel
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
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=TrueDataclasses). - Zero Monkey-Patching: No longer alters your class's
__hash__or__eq__methods. Uses internalMutableStatetokens for safe identity tracking.
- Universal Compatibility: Works natively with unhashable objects (e.g., standard Pydantic models,
-
⚡ 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.
- Hot Path Acceleration: Direct
-
🐢 -> 🐇 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.
- Full support for
-
🚀 High Performance:
- Powered by
orjson: faster serialization than standardjson. - Native Types: Supports
datetime,UUID, andnumpyout of the box. - Smart Caching: Introspection results are cached (
O(1)overhead).
- Powered by
-
🔄 Deep Mutation Tracking:
- Detects changes like
user.settings.tags.append("new")automatically. - No more
flag_modified()or reassigning the whole object.
- Detects changes like
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:
-
Basic Pydantic: The standard workflow for mutation tracking.
-
Lazy Loading Benchmarks: Performance comparison between eager and lazy loading.
-
Dataclasses: Using the safe dataclass wrapper.
-
Attrs Support: Integration with the
attrslibrary. -
Async SQLAlchemy: Integration with
AsyncSessionandaiosqlite. -
Deep Nesting: Tracking changes in lists of dictionaries of models.
-
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.