{"id":1724,"library":"sqlalchemy-jsonfield","title":"SQLAlchemy JSONField","description":"`sqlalchemy-jsonfield` provides a `JSONField` implementation for SQLAlchemy, allowing Python dictionaries to be stored in database JSON columns. It includes `JSONMutableDict` for automatic change tracking of mutable dictionary operations. The current stable version is 1.0.2, and it follows an infrequent, maintenance-focused release cadence.","status":"active","version":"1.0.2","language":"en","source_language":"en","source_url":"https://github.com/penguinolog/sqlalchemy_jsonfield","tags":["SQLAlchemy","JSON","ORM","Database","Data Types"],"install":[{"cmd":"pip install sqlalchemy-jsonfield","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for ORM integration and database interaction","package":"SQLAlchemy","optional":false}],"imports":[{"symbol":"JSONField","correct":"from sqlalchemy_jsonfield import JSONField"},{"note":"Required for SQLAlchemy to detect in-place modifications to JSON dictionary data.","symbol":"JSONMutableDict","correct":"from sqlalchemy_jsonfield import JSONMutableDict"}],"quickstart":{"code":"import sqlalchemy as sa\nfrom sqlalchemy.ext.declarative import declarative_base\nfrom sqlalchemy.orm import sessionmaker\n\nfrom sqlalchemy_jsonfield import JSONField, JSONMutableDict\n\n# Define the base for declarative models\nBase = declarative_base()\n\n# Define a model with a JSONField\nclass Data(Base):\n    __tablename__ = 'data'\n    id = sa.Column(sa.Integer, primary_key=True)\n    # Use JSONField with JSONMutableDict to enable automatic change tracking\n    json_data = sa.Column(JSONField(JSONMutableDict), default={})\n\n# Setup database engine and session\nengine = sa.create_engine('sqlite:///:memory:')\nBase.metadata.create_all(engine)\nSession = sessionmaker(bind=engine)\nsession = Session()\n\ntry:\n    # Create a new item\n    item = Data(json_data={'initial_key': 'initial_value', 'list_data': [1, 2]})\n    session.add(item)\n    session.commit()\n    print(f\"Created item ID: {item.id}, Data: {item.json_data}\")\n\n    # Retrieve the item\n    retrieved_item = session.query(Data).filter_by(id=item.id).first()\n    print(f\"Retrieved item ID: {retrieved_item.id}, Data: {retrieved_item.json_data}\")\n\n    # Update the JSON data in-place (changes detected by JSONMutableDict)\n    retrieved_item.json_data['new_key'] = 'new_value'\n    retrieved_item.json_data['list_data'].append(3)\n    session.commit()\n    print(f\"Updated item ID: {retrieved_item.id}, Data: {retrieved_item.json_data}\")\n\n    # Verify update by re-retrieving\n    verified_item = session.query(Data).filter_by(id=item.id).first()\n    print(f\"Verified item ID: {verified_item.id}, Data: {verified_item.json_data}\")\n\nfinally:\n    session.close()\n","lang":"python","description":"This quickstart demonstrates how to define a model with a `JSONField` that uses `JSONMutableDict` for automatic change detection. It shows creating, retrieving, and updating JSON data in-place, with changes being correctly persisted to an in-memory SQLite database."},"warnings":[{"fix":"Always use `JSONField(JSONMutableDict)` when you intend to modify the JSON dictionary in-place and have those changes automatically detected and persisted by SQLAlchemy.","message":"Failing to use `JSONMutableDict` will prevent SQLAlchemy from detecting in-place modifications to the JSON data. If you define a `JSONField` as `sa.Column(JSONField(dict))` instead of `sa.Column(JSONField(JSONMutableDict))`, changes like `instance.json_data['key'] = 'value'` will not be saved unless the entire dictionary is reassigned (`instance.json_data = new_dict`).","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"If your application relied on `ujson` behavior, ensure you explicitly pass `json=ujson` to `JSONField(..., json=ujson)` when initializing your column. Otherwise, be aware that serialization might now use Python's standard `json` module.","message":"Prior to version 0.7.0, `sqlalchemy-jsonfield` might have implicitly or explicitly relied on the `ujson` library for serialization. From version 0.7.0 onwards, it defaults to Python's standard `json` library and allows specifying a custom JSON library (e.g., `json=ujson`) via the `JSONField` constructor. This change could subtly alter serialization behavior or performance if your application implicitly depended on `ujson`'s characteristics.","severity":"breaking","affected_versions":"<0.7.0 to 0.7.0+"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}