{"id":1547,"library":"marshmallow-sqlalchemy","title":"marshmallow-sqlalchemy","description":"marshmallow-sqlalchemy provides integration between the SQLAlchemy ORM and the marshmallow (de)serialization library. It simplifies creating schemas for SQLAlchemy models, enabling automatic field generation and handling of relationships. The current version is 1.5.0, and it follows a release cadence generally aligned with its core dependencies, marshmallow and SQLAlchemy, with major updates addressing compatibility and new features.","status":"active","version":"1.5.0","language":"en","source_language":"en","source_url":"https://github.com/marshmallow-code/marshmallow-sqlalchemy","tags":["serialization","deserialization","orm","sqlalchemy","marshmallow","data-validation"],"install":[{"cmd":"pip install marshmallow-sqlalchemy","lang":"bash","label":"Install marshmallow-sqlalchemy"}],"dependencies":[{"reason":"Core (de)serialization library.","package":"marshmallow","optional":false},{"reason":"Core ORM library.","package":"SQLAlchemy","optional":false}],"imports":[{"note":"Automatically generates a schema from a SQLAlchemy model.","symbol":"SQLAlchemyAutoSchema","correct":"from marshmallow_sqlalchemy import SQLAlchemyAutoSchema"},{"note":"Allows manual definition of a schema for a SQLAlchemy model.","symbol":"SQLAlchemySchema","correct":"from marshmallow_sqlalchemy import SQLAlchemySchema"}],"quickstart":{"code":"import datetime\nfrom sqlalchemy import create_engine, Column, Integer, String, DateTime\nfrom sqlalchemy.orm import sessionmaker, declarative_base\nfrom marshmallow_sqlalchemy import SQLAlchemyAutoSchema\nfrom marshmallow import fields\n\n# 1. Define SQLAlchemy Base and Model\nBase = declarative_base()\n\nclass User(Base):\n    __tablename__ = 'users'\n    id = Column(Integer, primary_key=True)\n    name = Column(String(50), nullable=False)\n    email = Column(String(100), unique=True, nullable=False)\n    created_at = Column(DateTime, default=datetime.datetime.now)\n\n    def __repr__(self):\n        return f\"<User(id={self.id}, name='{self.name}')>\"\n\n# 2. Set up database (in-memory SQLite for example)\nengine = create_engine('sqlite:///:memory:')\nBase.metadata.create_all(engine)\nSession = sessionmaker(bind=engine)\nsession = Session()\n\n# 3. Define Marshmallow Schema for the User model\nclass UserSchema(SQLAlchemyAutoSchema):\n    class Meta:\n        model = User\n        load_instance = True  # Optional: Allows loading data into existing instances\n        sqla_session = session # Essential for relationship handling\n        # fields = ('id', 'name', 'email', 'created_at') # Explicit fields\n\n    # Example of overriding a field (optional)\n    created_at = fields.DateTime(format='%Y-%m-%d %H:%M:%S')\n\n# 4. Usage Example\nuser_data = {\n    'name': 'Alice Smith',\n    'email': 'alice@example.com'\n}\n\n# Create a schema instance\nuser_schema = UserSchema()\n\n# Deserialize (load) data to create a new User object\nnew_user = user_schema.load(user_data, session=session)\nsession.add(new_user)\nsession.commit()\n\nprint(f\"Created user: {new_user}\")\n\n# Serialize (dump) an existing User object\nserialized_user = user_schema.dump(new_user)\nprint(f\"Serialized user: {serialized_user}\")\n\n# Update an existing user\nupdate_data = {'name': 'Alicia Smith'}\nalice = session.query(User).filter_by(email='alice@example.com').first()\nupdated_user = user_schema.load(update_data, instance=alice, session=session)\nsession.add(updated_user)\nsession.commit()\n\nprint(f\"Updated user: {updated_user}\")\n\nsession.close()","lang":"python","description":"This quickstart demonstrates how to define a SQLAlchemy model, create a corresponding `SQLAlchemyAutoSchema`, and then use it to serialize (dump) and deserialize (load) data, including creating new instances and updating existing ones. It highlights the importance of passing the `session` to the schema for full functionality, especially with relationships."},"warnings":[{"fix":"Instead of `UserSchema(load_instance=True).load(data)`, use `user_schema.load(data, instance=existing_object)`. For creating new instances, simply `user_schema.load(data)`.","message":"The `load_instance` argument to `SQLAlchemySchema` and `SQLAlchemyAutoSchema` constructors was removed in v1.0.0. Its functionality moved to the `load` method.","severity":"breaking","affected_versions":"0.x to 1.x"},{"fix":"Pass `session=your_sqlalchemy_session` to the schema constructor (e.g., `UserSchema(session=session)`) or define `Meta.sqla_session = your_sqlalchemy_session` within your schema's `Meta` class.","message":"In v1.0.0, the `session` argument to `SQLAlchemySchema` and `SQLAlchemyAutoSchema` constructors no longer defaults to `None`. If `Meta.sqla_session` is not defined, you must pass the `session` explicitly when initializing the schema if you have relationship fields.","severity":"breaking","affected_versions":"0.x to 1.x"},{"fix":"For serialization, ensure your SQLAlchemy query uses eager loading (e.g., `session.query(Parent).options(joinedload(Parent.children))`) before passing objects to the schema. For deserialization, ensure your nested schema correctly handles the relationship (e.g., by setting `partial=True` if necessary for updates).","message":"Nesting SQLAlchemy models with relationships can lead to N+1 query problems if not handled carefully, and may require eager loading.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Define custom fields directly as class attributes in your `SQLAlchemyAutoSchema` subclass (e.g., `my_field = fields.String(data_key='custom_name')`) rather than inside the `Meta` class.","message":"Field overrides in `SQLAlchemyAutoSchema` must be placed directly in the schema class, not within the `Meta` class.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-09T00:00:00.000Z","next_check":"2026-07-08T00:00:00.000Z"}