SQLAlchemy 2.0 Documentation
SQLAlchemy ORM
- ORM Quick Start
- ORM Mapped Class Configuration
- ORM Mapped Class Overview
- Mapping Classes with Declarative
- Integration with dataclasses and attrs
- SQL Expressions as Mapped Attributes
- Changing Attribute Behavior
- Composite Column Types
- Mapping Class Inheritance Hierarchies
- Non-Traditional Mappings
- Configuring a Version Counter
- Class Mapping API
- Mapping SQL Expressions
- Relationship Configuration
- ORM Querying Guide
- Using the Session
- Events and Internals
- ORM Extensions
- ORM Examples
Project Versions
- Previous: Mapping Classes with Declarative
- Next: Table Configuration with Declarative
- Up: Home
- On this page:
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:
from sqlalchemy.orm import DeclarativeBase
# declarative base class
class Base(DeclarativeBase):
pass
The Declarative Base class may also be created given an existing
registry
by assigning it as a class variable named
registry
:
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import registry
reg = registry()
# declarative base class
class Base(DeclarativeBase):
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:
from datetime import datetime
from typing import List
from typing import Optional
from sqlalchemy import ForeignKey
from sqlalchemy import func
from sqlalchemy import Integer
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship
class Base(DeclarativeBase):
pass
class User(Base):
__tablename__ = "user"
id = mapped_column(Integer, primary_key=True)
name: Mapped[str]
fullname: Mapped[Optional[str]]
nickname: Mapped[Optional[str]] = mapped_column(String(64))
create_date: Mapped[datetime] = mapped_column(insert_default=func.now())
addresses: Mapped[List["Address"]] = relationship(back_populates="user")
class Address(Base):
__tablename__ = "address"
id = mapped_column(Integer, primary_key=True)
user_id = mapped_column(ForeignKey("user.id"))
email_address: Mapped[str]
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:
from datetime import datetime
from typing import List
from typing import Optional
from sqlalchemy import ForeignKey
from sqlalchemy import func
from sqlalchemy import Integer
from sqlalchemy import String
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import registry
from sqlalchemy.orm import relationship
mapper_registry = registry()
@mapper_registry.mapped
class User:
__tablename__ = "user"
id = mapped_column(Integer, primary_key=True)
name: Mapped[str]
fullname: Mapped[Optional[str]]
nickname: Mapped[Optional[str]] = mapped_column(String(64))
create_date: Mapped[datetime] = mapped_column(insert_default=func.now())
addresses: Mapped[List["Address"]] = relationship(back_populates="user")
@mapper_registry.mapped
class Address:
__tablename__ = "address"
id = mapped_column(Integer, primary_key=True)
user_id = mapped_column(ForeignKey("user.id"))
email_address: Mapped[str]
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:
from sqlalchemy.orm import registry
mapper_registry = registry()
@mapper_registry.mapped
class Person:
__tablename__ = "person"
person_id = mapped_column(Integer, primary_key=True)
type = mapped_column(String, nullable=False)
__mapper_args__ = {
"polymorphic_on": type,
"polymorphic_identity": "person",
}
@mapper_registry.mapped
class Employee(Person):
__tablename__ = "employee"
person_id = mapped_column(ForeignKey("person.person_id"), primary_key=True)
__mapper_args__ = {
"polymorphic_identity": "employee",
}
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.
flambé! the dragon and The Alchemist image designs created and generously donated by Rotem Yaari.
Created using Sphinx 7.2.6. Documentation last generated: Thu 12 Dec 2024 05:39:06 PM EST