Declarative Mapping Styles

As introduced at Declarative Mapping, the Declarative Mapping is the typical way that mappings are constructed in modern SQLAlchemy. This section will provide an overview of forms that may be used for Declarative mapper configuration.

Using a Declarative Base Class

The most common approach is to generate a “Declarative Base” class by subclassing the DeclarativeBase superclass:

  1. from sqlalchemy.orm import DeclarativeBase
  3. # declarative base class
  4. class Base(DeclarativeBase):
  5.     pass

The Declarative Base class may also be created given an existing registry by assigning it as a class variable named registry:

  1. from sqlalchemy.orm import DeclarativeBase
  2. from sqlalchemy.orm import registry
  4. reg = registry()
  7. # declarative base class
  8. class Base(DeclarativeBase):
  9.     registry = reg

Changed in version 2.0: The DeclarativeBase superclass supersedes the use of the declarative_base() function and registry.generate_base() methods; the superclass approach integrates with PEP 484 tools without the use of plugins. See ORM Declarative Models for migration notes.

With the declarative base class, new mapped classes are declared as subclasses of the base:

  1. from datetime import datetime
  2. from typing import Optional
  4. from sqlalchemy import ForeignKey
  5. from sqlalchemy import func
  6. from sqlalchemy import Integer
  7. from sqlalchemy import String
  8. from sqlalchemy.orm import DeclarativeBase
  9. from sqlalchemy.orm import Mapped
  10. from sqlalchemy.orm import mapped_column
  11. from sqlalchemy.orm import relationship
  14. class Base(DeclarativeBase):
  15.     pass
  18. class User(Base):
  19.     __tablename__ = "user"
  21.     id = mapped_column(Integer, primary_key=True)
  22.     name: Mapped[str]
  23.     fullname: Mapped[Optional[str]]
  24.     nickname: Mapped[Optional[str]] = mapped_column(String(64))
  25.     create_date: Mapped[datetime] = mapped_column(insert_default=func.now())
  27.     addresses: Mapped[list["Address"]] = relationship(back_populates="user")
  30. class Address(Base):
  31.     __tablename__ = "address"
  33.     id = mapped_column(Integer, primary_key=True)
  34.     user_id = mapped_column(ForeignKey("user.id"))
  35.     email_address: Mapped[str]
  37.     user: Mapped["User"] = relationship(back_populates="addresses")

Above, the Base class serves as a base for new classes that are to be mapped, as above new mapped classes User and Address are constructed.

For each subclass constructed, the body of the class then follows the declarative mapping approach which defines both a Table as well as a Mapper object behind the scenes which comprise a full mapping.

See also

Table Configuration with Declarative - describes how to specify the components of the mapped Table to be generated, including notes and options on the use of the mapped_column() construct and how it interacts with the Mapped annotation type

Mapper Configuration with Declarative - describes all other aspects of ORM mapper configuration within Declarative including relationship() configuration, SQL expressions and Mapper parameters

Declarative Mapping using a Decorator (no declarative base)

As an alternative to using the “declarative base” class is to apply declarative mapping to a class explicitly, using either an imperative technique similar to that of a “classical” mapping, or more succinctly by using a decorator. The registry.mapped() function is a class decorator that can be applied to any Python class with no hierarchy in place. The Python class otherwise is configured in declarative style normally.

The example below sets up the identical mapping as seen in the previous section, using the registry.mapped() decorator rather than using the DeclarativeBase superclass:

  1. from datetime import datetime
  2. from typing import Optional
  4. from sqlalchemy import ForeignKey
  5. from sqlalchemy import func
  6. from sqlalchemy import Integer
  7. from sqlalchemy import String
  8. from sqlalchemy.orm import Mapped
  9. from sqlalchemy.orm import mapped_column
  10. from sqlalchemy.orm import registry
  11. from sqlalchemy.orm import relationship
  13. mapper_registry = registry()
  16. @mapper_registry.mapped
  17. class User:
  18.     __tablename__ = "user"
  20.     id = mapped_column(Integer, primary_key=True)
  21.     name: Mapped[str]
  22.     fullname: Mapped[Optional[str]]
  23.     nickname: Mapped[Optional[str]] = mapped_column(String(64))
  24.     create_date: Mapped[datetime] = mapped_column(insert_default=func.now())
  26.     addresses: Mapped[list["Address"]] = relationship(back_populates="user")
  29. @mapper_registry.mapped
  30. class Address:
  31.     __tablename__ = "address"
  33.     id = mapped_column(Integer, primary_key=True)
  34.     user_id = mapped_column(ForeignKey("user.id"))
  35.     email_address: Mapped[str]
  37.     user: Mapped["User"] = relationship(back_populates="addresses")

When using the above style, the mapping of a particular class will only proceed if the decorator is applied to that class directly. For inheritance mappings (described in detail at Mapping Class Inheritance Hierarchies), the decorator should be applied to each subclass that is to be mapped:

  1. from sqlalchemy.orm import registry
  3. mapper_registry = registry()
  6. @mapper_registry.mapped
  7. class Person:
  8.     __tablename__ = "person"
  10.     person_id = mapped_column(Integer, primary_key=True)
  11.     type = mapped_column(String, nullable=False)
  13.     __mapper_args__ = {
  14.         "polymorphic_on": type,
  15.         "polymorphic_identity": "person",
  16.     }
  19. @mapper_registry.mapped
  20. class Employee(Person):
  21.     __tablename__ = "employee"
  23.     person_id = mapped_column(ForeignKey("person.person_id"), primary_key=True)
  25.     __mapper_args__ = {
  26.         "polymorphic_identity": "employee",
  27.     }

Both the declarative table and imperative table table configuration styles may be used with either the Declarative Base or decorator styles of Declarative mapping.

The decorator form of mapping is useful when combining a SQLAlchemy declarative mapping with other class instrumentation systems such as dataclasses and attrs, though note that SQLAlchemy 2.0 now features dataclasses integration with Declarative Base classes as well.