BaseDatabaseModel

Base class for database models -- persistence-layer data schema definitions that map domain aggregates to specific storage technologies. Database models are typically auto-generated but can be customized for adapter-specific optimizations.

Bases: Element, OptionsMixin

Base class for database models -- persistence-layer representations that map between domain aggregates/entities and database-specific schemas.

Database models are the bridge between the domain model and the storage layer. Each persistence adapter (SQLAlchemy, Elasticsearch, etc.) provides its own concrete subclass. Protean auto-generates a default database model for every aggregate; use @domain.model only when you need to customize the schema mapping (e.g. column names, indexes, JSON serialization).

Subclasses must implement from_entity() and to_entity() for bidirectional conversion between domain objects and database records.

Meta Options

Option	Type	Description
part_of	type	The aggregate or entity this model maps. Required.
database	str	The database provider name (default: "default").
schema_name	str	Override the storage table/collection name.

derive_schema_name classmethod

derive_schema_name() -> str

Derive the storage table/collection name.

Uses meta_.schema_name if explicitly set, otherwise falls back to the schema name of the associated aggregate or entity.

RETURNS	DESCRIPTION
str	The resolved schema name. TYPE: str

Source code in src/protean/core/database_model.py

@classmethod
def derive_schema_name(cls) -> str:
    """Derive the storage table/collection name.

    Uses ``meta_.schema_name`` if explicitly set, otherwise falls back
    to the schema name of the associated aggregate or entity.

    Returns:
        str: The resolved schema name.
    """
    if hasattr(cls.meta_, "schema_name") and cls.meta_.schema_name:
        return cls.meta_.schema_name
    else:
        return cls.meta_.part_of.meta_.schema_name

from_entity abstractmethod classmethod

from_entity(entity: Any) -> Any

Convert a domain entity/aggregate into a database model instance.

Implementors should extract field values from the domain object and map them to the database-specific representation.

PARAMETER	DESCRIPTION
entity	The domain entity or aggregate to convert. TYPE: BaseEntity

RETURNS	DESCRIPTION
Any	The database model instance ready for persistence.

Source code in src/protean/core/database_model.py

@classmethod
@abstractmethod
def from_entity(cls, entity: Any) -> Any:
    """Convert a domain entity/aggregate into a database model instance.

    Implementors should extract field values from the domain object and
    map them to the database-specific representation.

    Args:
        entity (BaseEntity): The domain entity or aggregate to convert.

    Returns:
        The database model instance ready for persistence.
    """

to_entity abstractmethod classmethod

to_entity(*args: Any, **kwargs: Any) -> BaseEntity

Convert a database record back into a domain entity/aggregate.

Implementors should reconstruct the domain object from the database-specific representation.

RETURNS	DESCRIPTION
BaseEntity	The reconstituted domain entity or aggregate. TYPE: BaseEntity

Source code in src/protean/core/database_model.py

@classmethod
@abstractmethod
def to_entity(cls, *args: Any, **kwargs: Any) -> "BaseEntity":
    """Convert a database record back into a domain entity/aggregate.

    Implementors should reconstruct the domain object from the
    database-specific representation.

    Returns:
        BaseEntity: The reconstituted domain entity or aggregate.
    """