Basic change tracking

This is essentially the SQLAlchemy mutable JSON recipe. We define a simple author model which list the author’s name and a property handles for various social media handles used:

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

Or, using the declarative mapping style:

class Category(Base):
    __tablename__ = "categories"

    id = mapped_column(Integer, primary_key=True)
    created_at: Mapped[DateTime] = mapped_column(DateTime, default=datetime.now)
    updated_at: Mapped[DateTime] = mapped_column(
        DateTime, default=datetime.now, onupdate=datetime.now
    )
    keywords: Mapped[list[str]] = mapped_column(MutableJson)

The example below loads one of the existing authors and retrieves the mapping of social media handles. The error in the twitter handle is then corrected and committed. The change is detected by SQLAlchemy and the appropriate UPDATE statement is generated.

>>> author = session.query(Author).first()
>>> author.handles
{'twitter': '@JohnDoe', 'facebook': 'JohnDoe'}
>>> author.handles['twitter'] = '@JDoe'
>>> session.commit()
>>> author.handles
{'twitter': '@JDoe', 'facebook': 'JohnDoe'}

Nested change tracking

The example below defines a simple model for articles. One of the properties on this model is a mutable JSON structure called references which includes a count of links that the article contains, grouped by domain:

class Article(Base):
    author = Column(ForeignKey('author.name'))
    content = Column(Text)
    references = Column(NestedMutableJson)

With this in place, an existing article is loaded and its current references inspected. Following that, the count for one of these is increased by ten, and the session is committed:

>>> article = session.query(Article).first()
>>> article.references
{'github.com': {'edelooff/sqlalchemy-json': 4, 'zzzeek/sqlalchemy': 7}}
>>> article.references['github.com']['edelooff/sqlalchemy-json'] += 10
>>> session.commit()
>>> article.references
{'github.com': {'edelooff/sqlalchemy-json': 14, 'zzzeek/sqlalchemy': 7}}

Had the articles model used MutableJson like in the previous example this code would have failed. This is because the top level dictionary is never altered directly. The nested mutable ensures the change happening at the lower level bubbles up to the outermost container.

0.7.0

• Adds support for top-level list for MutableJson, rather than having that support only be available in the nested variant (https://github.com/edelooff/sqlalchemy-json/pull/51)

• Adds pytest as development dependency

0.6.0

• Fixes pickling support (https://github.com/edelooff/sqlalchemy-json/issues/36)

• Drops python 2.x support (previously claimed, but already broken for some time)

• Removes test runners for CPython 3.6 since Github actions support has been dropped

0.5.0

• Fixes a lingering Python 3 compatibility issue (cmp parameter for TrackedList.sort)

• Adds pickling and unpickling support (https://github.com/edelooff/sqlalchemy-json/pull/28)

• Adds tracking for dictionary in-place updates (https://github.com/edelooff/sqlalchemy-json/pull/33)

0.4.0

• Adds a type creation function to allow for custom or alternate serialization types. This allows for a way around the regression in SQLite compatibility introduced by v0.3.0.

0.3.0

• Switches JSON base type to sqlalchemy.types.JSON from deprecated JSON type provided by SQLAlchemy-utils.

0.2.2

• Fixes a bug where assigning None to the column resulted in an error (https://github.com/edelooff/sqlalchemy-json/issues/10)

0.2.1

• Fixes a typo in the README found after uploading 0.2.0 to PyPI.

0.2.0 (unreleased)

• Now uses JSONType provided by SQLAlchemy-utils to handle backend storage;

• Backwards incompatible: Changed class name JsonObject to MutableJson and NestedJsonObject to NestedMutableJson

• Outermost container for NestedMutableJson can now be an array (Python list)

0.1.0 (unreleased)

Initial version. This initially carried a 1.0.0 version number but has never been released on PyPI.