ORM Mapped Class Configuration

Detailed reference for ORM configuration, not including relationships, which are detailed at Relationship Configuration.

For a quick look at a typical ORM configuration, start with ORM Quick Start.

For an introduction to the concept of object relational mapping as implemented in SQLAlchemy, it’s first introduced in the SQLAlchemy Unified Tutorial at Using ORM Declarative Forms to Define Table Metadata.

• ORM Mapped Class Overview
  • ORM Mapping Styles
    • Declarative Mapping
    • Imperative Mapping
  • Mapped Class Essential Components
    • The class to be mapped
    • The table, or other from clause object
    • The properties dictionary
    • Other mapper configuration parameters
  • Mapped Class Behavior
    • Default Constructor
    • Maintaining Non-Mapped State Across Loads
    • Runtime Introspection of Mapped classes, Instances and Mappers
      • Inspection of Mapper objects
      • Inspection of Mapped Instances
• Mapping Classes with Declarative
  • Declarative Mapping Styles
    • Using a Declarative Base Class
    • Declarative Mapping using a Decorator (no declarative base)
  • Table Configuration with Declarative
    • Declarative Table with mapped_column()
      • ORM Annotated Declarative - Automated Mapping with Type Annotations
      • Dataclass features in mapped_column()
      • Accessing Table and Metadata
      • Declarative Table Configuration
      • Explicit Schema Name with Declarative Table
      • Setting Load and Persistence Options for Declarative Mapped Columns
      • Naming Declarative Mapped Columns Explicitly
      • Appending additional columns to an existing Declarative mapped class
    • ORM Annotated Declarative - Complete Guide
      • mapped_column() derives the datatype and nullability from the Mapped annotation
      • Customizing the Type Map
      • Union types inside the Type Map
      • Support for Type Alias Types (defined by PEP 695) and NewType
      • Mapping Multiple Type Configurations to Python Types
      • Mapping Whole Column Declarations to Python Types
      • Using Python Enum or pep-586 Literal types in the type map
    • Declarative with Imperative Table (a.k.a. Hybrid Declarative)
      • Alternate Attribute Names for Mapping Table Columns
      • Applying Load, Persistence and Mapping Options for Imperative Table Columns
    • Mapping Declaratively with Reflected Tables
      • Using DeferredReflection
      • Using Automap
      • Automating Column Naming Schemes from Reflected Tables
      • Mapping to an Explicit Set of Primary Key Columns
      • Mapping a Subset of Table Columns
  • Mapper Configuration with Declarative
    • Defining Mapped Properties with Declarative
    • Mapper Configuration Options with Declarative
      • Constructing mapper arguments dynamically
    • Other Declarative Mapping Directives
      • __declare_last__()
      • __declare_first__()
      • metadata
      • __abstract__
      • __table_cls__
  • Composing Mapped Hierarchies with Mixins
    • Augmenting the Base
    • Mixing in Columns
    • Mixing in Relationships
    • Mixing in _orm.column_property() and other _orm.MapperProperty classes
    • Using Mixins and Base Classes with Mapped Inheritance Patterns
      • Using _orm.declared_attr() with inheriting Table and Mapper arguments
      • Using _orm.declared_attr() to generate table-specific inheriting columns
    • Combining Table/Mapper Arguments from Multiple Mixins
    • Creating Indexes and Constraints with Naming Conventions on Mixins
• Integration with dataclasses and attrs
  • Declarative Dataclass Mapping
    • Class level feature configuration
    • Attribute Configuration
      • Column Defaults
      • Integration with Annotated
    • Using mixins and abstract superclasses
    • Relationship Configuration
    • Using Non-Mapped Dataclass Fields
    • Integrating with Alternate Dataclass Providers such as Pydantic
  • Applying ORM Mappings to an existing dataclass (legacy dataclass use)
    • Mapping pre-existing dataclasses using Declarative With Imperative Table
    • Mapping pre-existing dataclasses using Declarative-style fields
      • Using Declarative Mixins with pre-existing dataclasses
    • Mapping pre-existing dataclasses using Imperative Mapping
  • Applying ORM mappings to an existing attrs class
• SQL Expressions as Mapped Attributes
  • Using a Hybrid
  • Using column_property
    • Adding column_property() to an existing Declarative mapped class
    • Composing from Column Properties at Mapping Time
    • Using Column Deferral with column_property()
  • Using a plain descriptor
  • Query-time SQL expressions as mapped attributes
• Changing Attribute Behavior
  • Simple Validators
    • validates()
  • Using Custom Datatypes at the Core Level
  • Using Descriptors and Hybrids
  • Synonyms
    • synonym()
  • Operator Customization
• Composite Column Types
  • Working with Mapped Composite Column Types
  • Other mapping forms for composites
    • Map columns directly, then pass to composite
    • Map columns directly, pass attribute names to composite
    • Imperative mapping and imperative table
  • Using Legacy Non-Dataclasses
  • Tracking In-Place Mutations on Composites
  • Redefining Comparison Operations for Composites
  • Nesting Composites
  • Composite API
    • composite()
• Mapping Class Inheritance Hierarchies
  • Joined Table Inheritance
    • Relationships with Joined Inheritance
    • Loading Joined Inheritance Mappings
  • Single Table Inheritance
    • Resolving Column Conflicts with use_existing_column
    • Relationships with Single Table Inheritance
    • Building Deeper Hierarchies with polymorphic_abstract
    • Loading Single Inheritance Mappings
  • Concrete Table Inheritance
    • Concrete Polymorphic Loading Configuration
    • Abstract Concrete Classes
    • Classical and Semi-Classical Concrete Polymorphic Configuration
    • Relationships with Concrete Inheritance
    • Loading Concrete Inheritance Mappings
• Non-Traditional Mappings
  • Mapping a Class against Multiple Tables
  • Mapping a Class against Arbitrary Subqueries
  • Multiple Mappers for One Class
• Configuring a Version Counter
  • Simple Version Counting
  • Custom Version Counters / Types
  • Server Side Version Counters
  • Programmatic or Conditional Version Counters
• Class Mapping API
  • registry
    • registry.__init__()
    • registry.as_declarative_base()
    • registry.configure()
    • registry.dispose()
    • registry.generate_base()
    • registry.map_declaratively()
    • registry.map_imperatively()
    • registry.mapped()
    • registry.mapped_as_dataclass()
    • registry.mappers
    • registry.update_type_annotation_map()
  • add_mapped_attribute()
  • column_property()
  • declarative_base()
  • declarative_mixin()
  • as_declarative()
  • mapped_column()
  • declared_attr
    • declared_attr.cascading
    • declared_attr.directive
  • DeclarativeBase
    • DeclarativeBase.__mapper__
    • DeclarativeBase.__mapper_args__
    • DeclarativeBase.__table__
    • DeclarativeBase.__table_args__
    • DeclarativeBase.__tablename__
    • DeclarativeBase.metadata
    • DeclarativeBase.registry
  • DeclarativeBaseNoMeta
    • DeclarativeBaseNoMeta.__mapper__
    • DeclarativeBaseNoMeta.__mapper_args__
    • DeclarativeBaseNoMeta.__table__
    • DeclarativeBaseNoMeta.__table_args__
    • DeclarativeBaseNoMeta.__tablename__
    • DeclarativeBaseNoMeta.metadata
    • DeclarativeBaseNoMeta.registry
  • has_inherited_table()
  • synonym_for()
  • object_mapper()
  • class_mapper()
  • configure_mappers()
  • clear_mappers()
  • identity_key()
  • polymorphic_union()
  • orm_insert_sentinel()
  • reconstructor()
  • Mapper
    • Mapper.__init__()
    • Mapper.add_properties()
    • Mapper.add_property()
    • Mapper.all_orm_descriptors
    • Mapper.attrs
    • Mapper.base_mapper
    • Mapper.c
    • Mapper.cascade_iterator()
    • Mapper.class_
    • Mapper.class_manager
    • Mapper.column_attrs
    • Mapper.columns
    • Mapper.common_parent()
    • Mapper.composites
    • Mapper.concrete
    • Mapper.configured
    • Mapper.entity
    • Mapper.get_property()
    • Mapper.get_property_by_column()
    • Mapper.identity_key_from_instance()
    • Mapper.identity_key_from_primary_key()
    • Mapper.identity_key_from_row()
    • Mapper.inherits
    • Mapper.is_mapper
    • Mapper.is_sibling()
    • Mapper.isa()
    • Mapper.iterate_properties
    • Mapper.local_table
    • Mapper.mapped_table
    • Mapper.mapper
    • Mapper.non_primary
    • Mapper.persist_selectable
    • Mapper.polymorphic_identity
    • Mapper.polymorphic_iterator()
    • Mapper.polymorphic_map
    • Mapper.polymorphic_on
    • Mapper.primary_key
    • Mapper.primary_key_from_instance()
    • Mapper.primary_mapper()
    • Mapper.relationships
    • Mapper.selectable
    • Mapper.self_and_descendants
    • Mapper.single
    • Mapper.synonyms
    • Mapper.tables
    • Mapper.validators
    • Mapper.with_polymorphic_mappers
  • MappedAsDataclass
  • MappedClassProtocol