Skip to content
Back to top
View this page

# marshmallow-sqlalchemy

SQLAlchemy integration with the marshmallow (de)serialization library.

Release v1.0.0 (Changelog)

## Declare your models

SQLAlchemy 1.4

    import sqlalchemy as sa
    from sqlalchemy.orm import (
        DeclarativeBase,
        backref,
        relationship,
        sessionmaker,
    )

    from marshmallow_sqlalchemy import SQLAlchemySchema, auto_field

    engine = sa.create_engine("sqlite:///:memory:")
    Session = sessionmaker(engine)

    class Base(DeclarativeBase):
        pass

    class Author(Base):
        __tablename__ = "authors"
        id = sa.Column(sa.Integer, primary_key=True)
        name = sa.Column(sa.String, nullable=False)

        def __repr__(self):
            return f"<Author(name={self.name!r})>"

    class Book(Base):
        __tablename__ = "books"
        id = sa.Column(sa.Integer, primary_key=True)
        title = sa.Column(sa.String)
        author_id = sa.Column(sa.Integer, sa.ForeignKey("authors.id"))
        author = relationship("Author", backref=backref("books"))

SQLAlchemy 2

    import sqlalchemy as sa
    from sqlalchemy.orm import (
        DeclarativeBase,
        backref,
        relationship,
        sessionmaker,
        mapped_column,
        Mapped,
    )

    from marshmallow_sqlalchemy import SQLAlchemySchema, auto_field

    engine = sa.create_engine("sqlite:///:memory:")
    Session = sessionmaker(engine)

    class Base(DeclarativeBase):
        pass

    class Author(Base):
        __tablename__ = "authors"
        id: Mapped[int] = mapped_column(primary_key=True)
        name: Mapped[str] = mapped_column(nullable=False)

        def __repr__(self):
            return f"<Author(name={self.name!r})>"

    class Book(Base):
        __tablename__ = "books"
        id: Mapped[int] = mapped_column(primary_key=True)
        title: Mapped[str] = mapped_column()
        author_id: Mapped[int] = mapped_column(sa.ForeignKey("authors.id"))
        author: Mapped["Author"] = relationship("Author", backref=backref("books"))

## Generate marshmallow schemas

    from marshmallow_sqlalchemy import SQLAlchemySchema, auto_field

    class AuthorSchema(SQLAlchemySchema):
        class Meta:
            model = Author
            load_instance = True  # Optional: deserialize to model instances

        id = auto_field()
        name = auto_field()
        books = auto_field()

    class BookSchema(SQLAlchemySchema):
        class Meta:
            model = Book
            load_instance = True

        id = auto_field()
        title = auto_field()
        author_id = auto_field()

You can automatically generate fields for a model’s columns using `SQLAlchemyAutoSchema`. The following schema classes are equivalent to the above.

    from marshmallow_sqlalchemy import SQLAlchemyAutoSchema

    class AuthorSchema(SQLAlchemyAutoSchema):
        class Meta:
            model = Author
            include_relationships = True
            load_instance = True

    class BookSchema(SQLAlchemyAutoSchema):
        class Meta:
            model = Book
            include_fk = True
            load_instance = True

Make sure to declare `Models` before instantiating `Schemas`. Otherwise sqlalchemy.orm.configure_mappers() will run too soon and fail.

## (De)serialize your data

    author = Author(name="Chuck Paluhniuk")
    author_schema = AuthorSchema()
    book = Book(title="Fight Club", author=author)

    with Session() as session:
        session.add(author)
        session.add(book)
        session.commit()

        dump_data = author_schema.dump(author)
        print(dump_data)
        # {'id': 1, 'name': 'Chuck Paluhniuk', 'books': [1]}

    with Session() as session:
        load_data = author_schema.load(dump_data, session=session)
        print(load_data)
        # <Author(name='Chuck Paluhniuk')>

## Get it now

    $ pip install -U marshmallow-sqlalchemy

Requires Python >= 3.9, marshmallow >= 3.18.0, and SQLAlchemy >= 1.4.40.

## Learn

Learn

- Recipes
  - Base `Schema` I
  - Base `Schema` II
  - Using `Related` to serialize relationships
  - Introspecting generated fields
  - Overriding generated fields
  - Automatically generating schemas for SQLAlchemy models
  - Smart `Nested` field
  - Transient object creation
  - Controlling instance loading

## API reference

API reference

- Top-level API
- Fields

## Project info

Project info

- Changelog
- Contributing guidelines
- Authors
- License