sqlalchemy-json

What it is and what it does

sqlalchemy-json extends SQLAlchemy with two mutation-tracked JSON column types: MutableJson for top-level changes and NestedMutableJson for changes anywhere in nested objects or arrays. When you modify a JSON column value in memory, the package detects that change and ensures SQLAlchemy generates the correct UPDATE statement on commit, rather than requiring you to manually flag the column as dirty or reassign the entire value.

The package wraps SQLAlchemy's native JSON type and provides custom tracking containers (dicts and lists) that bubble modifications up to the column level. You can also use the mutable_json_type utility to customize the backing database type—for example, to use PostgreSQL's JSONB or to serialize to a non-JSON format. It has one runtime dependency: sqlalchemy.

Use it for:

• Store and modify social media handles or metadata objects in a single JSON column without reassigning the entire column on each edit.
• Track reference counts or nested statistics that change frequently without triggering full-column rewrites.
• Use PostgreSQL JSONB or other database-specific JSON types while maintaining change-tracking behavior.
• Serialize and track changes to non-JSON formats (e.g., custom string-encoded data) by providing a custom TypeDecorator.
• Persist top-level or deeply nested list modifications (e.g., tags, keywords) as a single atomic column.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Provides mutation-tracked JSON column types for SQLAlchemy that detect and persist changes to JSON data at the top level or nested within objects and arrays.

Yes, if you need automatic change tracking for JSON columns in SQLAlchemy. The package is stable and has no known vulnerabilities. However, maintenance is dormant—last release was over two years ago—so verify compatibility with your specific SQLAlchemy and Python versions before adopting it in new projects. For existing codebases already using it, the low install friction and permissive license make it safe to keep.

Install

sqlalchemy-json on PyPI

pip install sqlalchemy-json

uv add sqlalchemy-json

poetry add sqlalchemy-json

Installing sqlalchemy-json

Before you install

Low install friction; depends only on sqlalchemy. Maintenance is dormant—last release was 1080 days ago—but the repository is not archived and the package remains stable for its scope.

License in practice

BSD license (permissive); you may use, modify, and distribute this package freely in commercial and open-source projects with minimal restrictions.

Quickstart

pip install sqlalchemy-json

from sqlalchemy import Column, Text, create_engine
from sqlalchemy.orm import declarative_base
from sqlalchemy_json import MutableJson

Base = declarative_base()

class Author(Base):
    __tablename__ = 'authors'
    name = Column(Text)
    handles = Column(MutableJson)

# Changes to handles are tracked and persisted on commit
author.handles['twitter'] = '@NewHandle'
session.commit()

Verify before relying

• Current compatibility with the latest SQLAlchemy versions (last release was August 2023)
• Whether nested tracking works correctly with all modern Python versions supported by current SQLAlchemy

Package facts

Evidence: sqlalchemy_json-0.7.0-py3-none-any.whl

Keywords: sqlalchemy, json, mutable

Tags

More Database packages