oxyde-postgres 0.1.0__py3-none-any.whl

oxyde/models/base.py

@@ -0,0 +1,871 @@
+"""Model base class for defining database models.
+
+This module provides the foundation of the Oxyde ORM model system. It defines
+Model, a Pydantic v2 BaseModel subclass with database mapping capabilities.
+
+Architecture:
+    OxydeModelMeta (metaclass)
+        └── Intercepts field access for DSL queries (User.name → QueryField)
+        └── Tracks pending FK fields for lazy resolution
+        └── Creates ModelFieldDescriptor for each model field
+
+    Model (base class)
+        └── Inherits from pydantic.BaseModel for validation
+        └── Uses extra="ignore" to skip JOIN fields (author__id, author__name)
+        └── Auto-registers in global model registry if Meta.is_table = True
+        └── Provides QueryManager via Model.objects for CRUD operations
+        └── Instance methods: save(), delete(), refresh()
+        └── Lifecycle hooks: pre_save, post_save, pre_delete, post_delete
+
+Key Components:
+    _db_meta (ClassVar[ModelMeta]):
+        Stores table-level metadata: table_name, schema, indexes, constraints.
+        Also holds field_metadata dict mapping field names to ColumnMeta.
+        Populated eagerly at class definition time via finalize_pending().
+
+    objects (ClassVar[QueryManager]):
+        Django-style manager for queries. Auto-created in __init_subclass__.
+        Example: User.objects.filter(age__gte=18).all()
+
+    _resolve_fk_fields():
+        Handles FK type annotations (field: Author) by auto-adding
+        the {field}_{pk} column (author_id: int) to the model.
+
+Internal Flow:
+    1. Class definition triggers OxydeModelMeta.__new__()
+    2. __init_subclass__() extracts Meta, creates _db_meta, registers table
+    3. OxydeModelMeta.__new__() calls finalize_pending() after Pydantic completes
+    4. finalize_pending() resolves FKs, parses field tags, caches PK and column_types
+
+Example:
+    class User(Model):
+        id: int | None = Field(default=None, db_pk=True)
+        name: str = Field(db_index=True)
+        email: str = Field(db_unique=True)
+
+        class Meta:
+            is_table = True
+            table_name = "users"
+
+        async def pre_save(self, *, is_create: bool, update_fields=None):
+            if is_create:
+                self.created_at = datetime.utcnow()
+
+    # Class-level DSL access (for queries)
+    User.name  # Returns QueryField for building filters
+
+    # Instance methods
+    user = User(name="Alice", email="alice@example.com")
+    await user.save()  # INSERT (pre_save → INSERT → post_save)
+    await user.refresh()  # Re-fetch from DB
+    await user.delete()  # DELETE (pre_delete → DELETE → post_delete)
+"""
+
+from __future__ import annotations
+
+import sys
+import typing as typing_module
+import warnings
+from collections.abc import Iterable
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    ForwardRef,
+    get_args,
+    get_origin,
+    get_type_hints,
+)
+
+from pydantic import BaseModel, ConfigDict
+from pydantic._internal._model_construction import ModelMetaclass
+from pydantic.errors import PydanticUndefinedAnnotation
+from pydantic.fields import FieldInfo, PydanticUndefined
+from typing_extensions import Self, dataclass_transform
+
+from oxyde.core import register_validator
+
+if TYPE_CHECKING:
+    from oxyde.queries.base import SupportsExecute
+    from oxyde.queries.manager import QueryManager
+
+from oxyde.exceptions import FieldError, ManagerError, NotFoundError
+from oxyde.models.field import Field, OxydeFieldInfo
+from oxyde.models.metadata import (
+    ColumnMeta,
+    ForeignKeyInfo,
+    ModelMeta,
+    RelationDescriptorBase,
+    RelationInfo,
+    column_type_for_meta,
+    is_column_field,
+)
+from oxyde.models.registry import finalize_pending, register_table
+from oxyde.models.serializers import _dump_update_data
+from oxyde.models.utils import (
+    _extract_constraints,
+    _extract_inner_constraints,
+    _unpack_annotated,
+    _unwrap_optional,
+)
+
+
+def _get_pk_field_name(model_cls: type) -> str:
+    """Get the primary key field name from a Model class.
+
+    Uses cached pk_field if available (model is finalized),
+    otherwise scans model_fields for db_pk=True.
+    Defaults to "id" if no PK found.
+    """
+    # Use cached PK if available (model is finalized)
+    if hasattr(model_cls, "_db_meta") and model_cls._db_meta.pk_field:
+        pk: str = model_cls._db_meta.pk_field
+        return pk
+
+    # Fallback: check model_fields directly for db_pk=True
+    if hasattr(model_cls, "model_fields"):
+        for field_name, field_info in model_cls.model_fields.items():
+            if isinstance(field_info, OxydeFieldInfo) and getattr(
+                field_info, "db_pk", False
+            ):
+                name: str = field_name
+                return name
+
+    return "id"
+
+
+class OxydeModelMeta(ModelMetaclass):
+    """Custom metaclass that exposes model fields as DSL descriptors."""
+
+    def __new__(mcs, name: str, bases: tuple, namespace: dict, **kwargs: Any) -> type:
+        """Create new Model class with auto-configured relation fields."""
+        # Auto-add default_factory=list for virtual relation fields BEFORE Pydantic
+        # This ensures fields with db_reverse_fk or db_m2m are not required
+        for value in namespace.values():
+            if isinstance(value, OxydeFieldInfo) and value.is_virtual:
+                if value.default is PydanticUndefined and value.default_factory is None:
+                    value.default_factory = list
+
+        cls: type[Model] = super().__new__(mcs, name, bases, namespace, **kwargs)
+
+        # Detect FK fields from Pydantic's processed model_fields
+        # This works on all Python versions (3.10-3.14+) because Pydantic
+        # has already resolved annotations regardless of lazy/eager evaluation
+        pending_fk_fields: list[tuple[str, Any, FieldInfo | None]] = []
+        for field_name, field_info in cls.model_fields.items():
+            if isinstance(field_info, OxydeFieldInfo) and field_info.is_virtual:
+                continue
+
+            annotation = field_info.annotation
+            inner_type, _ = _unwrap_optional(annotation)
+            if isinstance(inner_type, type) and issubclass(inner_type, BaseModel):
+                pending_fk_fields.append((field_name, annotation, field_info))
+            elif isinstance(inner_type, (str, ForwardRef)):
+                pending_fk_fields.append((field_name, annotation, field_info))
+
+        cls.__pending_fk_fields__ = pending_fk_fields
+        cls.__fk_fields_resolved__ = False
+
+        # Finalize all pending models AFTER Pydantic completes
+        # (model_fields is now populated). Resolves FKs, parses metadata, caches PK.
+        finalize_pending()
+
+        return cls
+
+    def __getattr__(cls, item: str) -> Any:
+        return super().__getattr__(item)  # type: ignore[misc]
+
+
+def _build_globalns(cls: type) -> dict[str, Any]:
+    """Build globalns dict for get_type_hints() with common ORM types."""
+    from oxyde.queries.manager import QueryManager
+    from oxyde.queries.select import Query
+
+    module = sys.modules.get(cls.__module__)
+    globalns = vars(module) if module is not None else {}
+    combined = {**typing_module.__dict__, **globalns}
+    combined.setdefault("Model", Model)
+    combined.setdefault("OxydeModel", Model)
+    combined.setdefault("ModelMeta", ModelMeta)
+    combined.setdefault("ColumnMeta", ColumnMeta)
+    combined.setdefault("ForeignKeyInfo", ForeignKeyInfo)
+    combined.setdefault("Query", Query)
+    combined.setdefault("QueryManager", QueryManager)
+    # typing.Self does not exist on 3.10; the inherited `objects` annotation
+    # references it, so resolution must see the typing_extensions fallback.
+    combined.setdefault("Self", Self)
+    return combined
+
+
+def _get_db_attr(field: FieldInfo, attr_name: str, default: Any = None) -> Any:
+    """Extract db_* attribute from OxydeFieldInfo or return default."""
+    if isinstance(field, OxydeFieldInfo):
+        return getattr(field, attr_name, default)
+    return default
+
+
+@dataclass_transform(
+    kw_only_default=True,
+    field_specifiers=(FieldInfo, Field, OxydeFieldInfo),
+)
+class Model(BaseModel, metaclass=OxydeModelMeta):
+    """Base class for Oxyde ORM models."""
+
+    model_config = ConfigDict(
+        ignored_types=(RelationDescriptorBase,),
+    )
+    _db_meta: ClassVar[ModelMeta]
+    # Parametrized by Self so `User.objects.first()` infers `User | None`
+    # on every subclass without the generated stubs.
+    objects: ClassVar[QueryManager[Self]]
+    _is_table: ClassVar[bool] = False
+    __pending_fk_fields__: ClassVar[list[tuple[str, Any, Any]]] = []
+    __fk_fields_resolved__: ClassVar[bool] = False
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+
+        module = sys.modules.get(cls.__module__)
+        if module is not None:
+            setattr(module, cls.__name__, cls)
+
+        # Extract Meta attributes
+        meta_dict: dict[str, Any] = {}
+        meta_cls = cls.__dict__.get("Meta")
+        if meta_cls is not None:
+            for attr in dir(meta_cls):
+                if not attr.startswith("_"):
+                    meta_dict[attr] = getattr(meta_cls, attr)
+
+        # Determine whether this class represents a table
+        is_table = bool(meta_dict.get("is_table", False))
+        cls._is_table = is_table
+
+        # Set table name if not provided
+        if "table_name" not in meta_dict and is_table:
+            meta_dict["table_name"] = cls.__name__.lower()
+
+        known_meta_keys = {
+            "is_table",
+            "table_name",
+            "schema",
+            "comment",
+            "indexes",
+            "unique_together",
+            "constraints",
+        }
+        indexes = list(meta_dict.get("indexes", []) or [])
+        unique_together = [
+            tuple(group) if not isinstance(group, tuple) else group
+            for group in (meta_dict.get("unique_together", []) or [])
+        ]
+        constraints = list(meta_dict.get("constraints", []) or [])
+        extra_meta = {
+            key: value for key, value in meta_dict.items() if key not in known_meta_keys
+        }
+
+        cls._db_meta = ModelMeta(
+            table_name=meta_dict.get("table_name"),
+            schema=meta_dict.get("schema"),
+            comment=meta_dict.get("comment"),
+            indexes=indexes,
+            unique_together=unique_together,
+            constraints=constraints,
+            extra=extra_meta,
+        )
+
+        relation_descriptors: list[tuple[str, Any]] = [
+            (name, value)
+            for name, value in cls.__dict__.items()
+            if getattr(value, "_is_relation_descriptor", False)
+        ]
+
+        # Initialize manager (async by default)
+        from oxyde.queries.manager import (  # local import to avoid circular dependency
+            QueryManager,
+        )
+
+        # `cls` is type[Model] here while the annotation binds Self per
+        # subclass; the instance is per-class, so the narrowing is correct.
+        cls.objects = QueryManager(cls)  # type: ignore[arg-type]
+
+        # Register validator with Rust core for server-side row validation
+        model_key = f"{cls.__module__}.{cls.__qualname__}"
+        validator = getattr(cls, "__pydantic_validator__", None)
+        if validator is not None:
+            try:
+                register_validator(model_key, validator)
+            except RuntimeError as exc:  # pragma: no cover - optional core feature
+                warnings.warn(
+                    f"Failed to register validator for {model_key}: {exc}",
+                    RuntimeWarning,
+                    stacklevel=2,
+                )
+
+        if is_table:
+            register_table(cls, overwrite=True)
+        else:
+            cls._db_meta.field_metadata = {}
+            cls._db_meta.relations = {}
+
+        if relation_descriptors and is_table:
+            for name, descriptor in relation_descriptors:
+                descriptor.contribute_to_model(cls, name)
+
+    @classmethod
+    def _compute_column_types(cls) -> None:
+        """Compute ColumnTypeSpec dicts and db_type overrides from field
+        metadata (cached in _db_meta)."""
+        if cls._db_meta.column_types is not None:
+            return  # Already computed
+
+        column_types: dict[str, dict] = {}
+        column_db_types: dict[str, str] = {}
+        reverse_map: dict[str, str] = {}
+        for field_name, meta in cls._db_meta.field_metadata.items():
+            # Virtual relation fields and FK model fields (author: Author)
+            # have no column of their own, nor a reverse mapping
+            if not is_column_field(meta):
+                continue
+            spec = column_type_for_meta(meta)
+            if spec is not None:
+                column_types[meta.db_column] = spec
+            # Preserve db_type overrides for array casts and JSON array lookups.
+            if meta.db_type is not None:
+                column_db_types[meta.db_column] = meta.db_type
+            # Cache reverse mapping where db_column differs from field_name
+            if meta.db_column != field_name:
+                reverse_map[meta.db_column] = field_name
+
+        cls._db_meta.column_types = column_types if column_types else None
+        cls._db_meta.column_db_types = column_db_types or None
+        cls._db_meta.reverse_column_map = reverse_map
+
+    @classmethod
+    def _resolve_fk_fields(cls) -> None:
+        """Resolve pending FK fields and add {field}_{pk} columns to the model."""
+        if getattr(cls, "__fk_fields_resolved__", False):
+            return
+        cls.__fk_fields_resolved__ = True
+
+        pending_fk = getattr(cls, "__pending_fk_fields__", [])
+        if not pending_fk:
+            return
+
+        # Get type hints to resolve forward references
+        try:
+            hints = get_type_hints(
+                cls,
+                include_extras=True,
+                globalns=_build_globalns(cls),
+                localns=dict(cls.__dict__),
+            )
+        except NameError:
+            # Forward reference not yet resolvable - skip for now
+            cls.__fk_fields_resolved__ = False
+            return
+
+        fields_to_add: list[tuple[str, Any, FieldInfo]] = []
+
+        for field_name, _annotation, field_info in pending_fk:
+            # Get resolved type hint
+            hint = hints.get(field_name)
+            if hint is None:
+                continue
+
+            base_hint, _ = _unpack_annotated(hint)
+            inner_type, is_optional = _unwrap_optional(base_hint)
+
+            # Check if it's a Model subclass
+            if not (isinstance(inner_type, type) and issubclass(inner_type, Model)):
+                continue
+
+            # Get target field: db_fk or auto-detect PK
+            target_model = inner_type
+            db_fk = None
+            if isinstance(field_info, OxydeFieldInfo):
+                db_fk = getattr(field_info, "db_fk", None)
+            target_field_name = db_fk or _get_pk_field_name(target_model)
+
+            # Get target field type from target model
+            target_field_info = target_model.model_fields.get(target_field_name)
+            if target_field_info is None:
+                fk_type: type = int  # fallback
+            else:
+                fk_annotation = target_field_info.annotation
+                fk_type_inner, _ = _unwrap_optional(fk_annotation)
+                fk_type = fk_type_inner if isinstance(fk_type_inner, type) else int
+
+            # Build FK column name: db_column or {field_name}_{target_field}
+            db_column = None
+            db_nullable = None
+            db_unique = False
+            db_index = False
+            db_index_name = None
+            db_index_method = None
+            if isinstance(field_info, OxydeFieldInfo):
+                db_column = getattr(field_info, "db_column", None)
+                db_nullable = getattr(field_info, "db_nullable", None)
+                db_unique = getattr(field_info, "db_unique", False)
+                db_index = getattr(field_info, "db_index", False)
+                db_index_name = getattr(field_info, "db_index_name", None)
+                db_index_method = getattr(field_info, "db_index_method", None)
+            fk_column_name = db_column or f"{field_name}_{target_field_name}"
+
+            # Check if this field already exists (avoid duplicates)
+            if fk_column_name in cls.model_fields:
+                continue
+
+            # Determine FK column type (nullable if original FK field is optional)
+            # db_nullable from virtual FK field applies to the real column
+            if is_optional:
+                fk_column_type = fk_type | None
+                fk_default = None
+            else:
+                fk_column_type = fk_type
+                fk_default = PydanticUndefined
+
+            # Carry column-level attributes from the virtual FK field over to
+            # the synthetic column — it is the real DB column, so db_unique
+            # and the index attributes must live on it.
+            fields_to_add.append(
+                (
+                    fk_column_name,
+                    fk_column_type,
+                    Field(
+                        default=fk_default,
+                        db_nullable=db_nullable,
+                        db_unique=db_unique,
+                        db_index=db_index,
+                        db_index_name=db_index_name,
+                        db_index_method=db_index_method,
+                    ),
+                )
+            )
+
+        if not fields_to_add:
+            return
+
+        # Add fields to model
+        added_fields: list[str] = []
+        for fk_column_name, fk_column_type, fk_field_info in fields_to_add:
+            cls.__annotations__[fk_column_name] = fk_column_type
+            # Preserve OxydeFieldInfo with db_nullable
+            fk_field_info.annotation = fk_column_type
+            cls.__pydantic_fields__[fk_column_name] = fk_field_info
+            added_fields.append(fk_column_name)
+
+        # Rebuild model to include new fields
+        # May fail if other forward refs are not yet resolvable
+        try:
+            cls.model_rebuild(force=True)
+        except PydanticUndefinedAnnotation:
+            # Forward ref not resolvable yet - revert and retry later
+            for fk_column_name in added_fields:
+                cls.__annotations__.pop(fk_column_name, None)
+                cls.__pydantic_fields__.pop(fk_column_name, None)
+            cls.__fk_fields_resolved__ = False
+
+    @classmethod
+    def _parse_field_tags(cls) -> None:
+        """Parse Annotated field tags and store them in metadata."""
+        cls._db_meta.field_metadata = {}
+        if not cls._is_table:
+            return
+
+        hints = get_type_hints(
+            cls,
+            include_extras=True,
+            globalns=_build_globalns(cls),
+            localns=dict(cls.__dict__),
+        )
+
+        for field_name, model_field in cls.model_fields.items():
+            # Get type hint for nullable detection and FK inference
+            hint = hints.get(field_name, model_field.annotation)
+            base_hint, _ = _unpack_annotated(hint)  # annotations not used anymore
+            python_type, optional_flag = _unwrap_optional(base_hint)
+
+            # Read db_* attributes (type-safe access via OxydeFieldInfo)
+            db_pk = _get_db_attr(model_field, "db_pk", False)
+            db_index = _get_db_attr(model_field, "db_index", False)
+            db_index_name = _get_db_attr(model_field, "db_index_name", None)
+            db_index_method = _get_db_attr(model_field, "db_index_method", None)
+            db_unique = _get_db_attr(model_field, "db_unique", False)
+            db_column = _get_db_attr(model_field, "db_column", None)
+            db_type = _get_db_attr(model_field, "db_type", None)
+            db_default = _get_db_attr(model_field, "db_default", None)
+            db_comment = _get_db_attr(model_field, "db_comment", None)
+            db_fk = _get_db_attr(model_field, "db_fk", None)
+            db_on_delete = _get_db_attr(model_field, "db_on_delete", "RESTRICT")
+            db_on_update = _get_db_attr(model_field, "db_on_update", "CASCADE")
+            db_nullable = _get_db_attr(model_field, "db_nullable", None)
+            db_reverse_fk = _get_db_attr(model_field, "db_reverse_fk", None)
+            db_m2m = _get_db_attr(model_field, "db_m2m", False)
+            db_through = _get_db_attr(model_field, "db_through", None)
+
+            # Foreign Key detection
+            # FK is defined by type annotation: field type must be Model
+            # db_fk parameter specifies target field (defaults to PK)
+            fk_info: ForeignKeyInfo | None = None
+            is_fk = isinstance(python_type, type) and issubclass(python_type, Model)
+
+            # Determine nullable:
+            # 1. If db_nullable explicitly set — use it
+            # 2. Otherwise — infer from type hint (X | None = nullable)
+            if db_nullable is not None:
+                nullable = db_nullable
+            else:
+                nullable = optional_flag
+
+            default_value = model_field.default
+            default_factory = getattr(model_field, "default_factory", None)
+
+            # Allow None default for optional fields (non-FK only)
+            # Only override if db_nullable was not explicitly set
+            if (
+                not is_fk
+                and not nullable
+                and db_nullable is None  # don't override explicit db_nullable
+                and not model_field.is_required()
+                and default_value is None
+                and default_value is not PydanticUndefined
+            ):
+                nullable = True
+
+            if is_fk:
+                target_key = f"{python_type.__module__}.{python_type.__qualname__}"
+
+                # Determine target field: db_fk or auto-detect PK
+                if db_fk:
+                    # Explicit target field specified
+                    target_field = db_fk
+                else:
+                    # Auto-detect PK field of target model
+                    target_field = _get_pk_field_name(python_type)
+
+                # FK column name: db_column override or {field_name}_{target_field}
+                column_name = db_column or f"{field_name}_{target_field}"
+
+                fk_info = ForeignKeyInfo(
+                    target=target_key,
+                    column_name=column_name,
+                    target_field=target_field,
+                    nullable=nullable,
+                    on_delete=db_on_delete,
+                    on_update=db_on_update,
+                )
+
+            # Extract type constraints (max_length, max_digits, decimal_places)
+            # For list fields, inner Annotated constraints override top-level
+            # (top-level max_length on list = list size, inner = element constraint)
+            constraints = _extract_constraints(model_field)
+            if get_origin(python_type) is list:
+                constraints.update(_extract_inner_constraints(model_field))
+
+            # Determine actual DB column name
+            if fk_info is not None:
+                # For FK fields, use FK column name
+                db_column_name = fk_info.column_name
+            else:
+                # For regular fields, use db_column or field name
+                db_column_name = db_column or field_name
+
+            # Build extras dict for additional metadata
+            extras_filtered: dict[str, Any] = {}
+            if db_reverse_fk:
+                extras_filtered["reverse_fk"] = db_reverse_fk
+            if db_m2m:
+                extras_filtered["m2m"] = True
+                if db_through:
+                    extras_filtered["through"] = db_through
+
+            # Populate _db_meta.relations for reverse FK and M2M fields
+            if db_reverse_fk or db_m2m:
+                # Extract target model from list[X] type
+                target_name: str | None = None
+                origin = get_origin(python_type)
+                if origin is list:
+                    list_args = get_args(python_type)
+                    if list_args:
+                        element_type = list_args[0]
+                        if isinstance(element_type, str):
+                            target_name = element_type
+                        elif isinstance(element_type, type):
+                            target_name = element_type.__name__
+
+                if target_name:
+                    if db_reverse_fk:
+                        # One-to-many (reverse FK) relation
+                        cls._db_meta.relations[field_name] = RelationInfo(
+                            name=field_name,
+                            kind="one_to_many",
+                            target=target_name,
+                            remote_field=db_reverse_fk,
+                            through=None,
+                        )
+                    elif db_m2m:
+                        # Many-to-many relation
+                        cls._db_meta.relations[field_name] = RelationInfo(
+                            name=field_name,
+                            kind="many_to_many",
+                            target=target_name,
+                            remote_field=None,
+                            through=db_through,
+                        )
+
+            column_meta = ColumnMeta(
+                name=field_name,
+                db_column=db_column_name,
+                python_type=python_type,
+                nullable=nullable,
+                db_type=db_type,
+                index=db_index,
+                index_name=db_index_name,
+                index_method=db_index_method,
+                unique=db_unique,
+                primary_key=db_pk,
+                comment=db_comment,
+                default=default_value,
+                default_factory=default_factory,
+                db_default=db_default,
+                max_length=constraints.get("max_length"),
+                max_digits=constraints.get("max_digits"),
+                decimal_places=constraints.get("decimal_places"),
+                foreign_key=fk_info,
+                checks=[],  # Field-level checks not supported yet
+                extra=extras_filtered,
+            )
+            cls._db_meta.field_metadata[field_name] = column_meta
+
+    @classmethod
+    def get_table_name(cls) -> str:
+        """Get the table name for this model."""
+        return cls._db_meta.table_name or cls.__name__.lower()
+
+    # =========================================================================
+    # Lifecycle Hooks
+    # =========================================================================
+
+    async def pre_save(
+        self,
+        *,
+        is_create: bool,
+        update_fields: set[str] | None = None,
+    ) -> None:
+        """Called before save/create. Override to add custom logic.
+
+        Args:
+            is_create: True if this is a new record, False if updating.
+            update_fields: Set of field names being updated, or None for all fields.
+
+        Example:
+            async def pre_save(self, *, is_create: bool, update_fields: set[str] | None = None) -> None:
+                if is_create:
+                    self.created_at = datetime.now()
+                if self.password and not self.password.startswith("$2b$"):
+                    self.password = await hash_password(self.password)
+        """
+
+    async def post_save(
+        self,
+        *,
+        is_create: bool,
+        update_fields: set[str] | None = None,
+    ) -> None:
+        """Called after save/create. Override to add custom logic.
+
+        Args:
+            is_create: True if this was a new record, False if updated.
+            update_fields: Set of field names that were updated, or None for all fields.
+
+        Example:
+            async def post_save(self, *, is_create: bool, update_fields: set[str] | None = None) -> None:
+                if is_create:
+                    await send_welcome_email(self.email)
+        """
+
+    async def pre_delete(self) -> None:
+        """Called before delete. Override to add custom logic.
+
+        Example:
+            async def pre_delete(self) -> None:
+                await cleanup_user_files(self.id)
+        """
+
+    async def post_delete(self) -> None:
+        """Called after delete. Override to add custom logic.
+
+        Example:
+            async def post_delete(self) -> None:
+                await notify_admin(f"User {self.email} deleted")
+        """
+
+    # =========================================================================
+    # Instance Methods
+    # =========================================================================
+
+    async def save(
+        self,
+        *,
+        client: SupportsExecute | None = None,
+        using: str | None = None,
+        update_fields: Iterable[str] | None = None,
+    ) -> Self:
+        manager = self.__class__.objects
+        pk_field = self.__class__._db_meta.pk_field
+        pk_value = getattr(self, pk_field) if pk_field else None
+        is_create = not (pk_field and pk_value not in (None, PydanticUndefined))
+
+        # Convert update_fields to set for hooks
+        update_fields_set: set[str] | None = None
+        if update_fields is not None:
+            update_fields_set = set(update_fields)
+
+        # Call pre_save hook
+        await self.pre_save(is_create=is_create, update_fields=update_fields_set)
+
+        if not is_create:
+            # Update specified fields or all fields (except PK)
+            if update_fields_set is not None:
+                # Validate that all specified fields exist
+                model_field_names = set(self.__class__.model_fields.keys())
+                invalid_fields = update_fields_set - model_field_names
+                if invalid_fields:
+                    inv = ", ".join(sorted(invalid_fields))
+                    msg = f"Invalid update_fields for {self.__class__.__name__}: {inv}"
+                    raise FieldError(msg)
+
+                # Resolve virtual FK fields to their synthetic columns
+                # e.g. "author" → "author_id" (Django-compatible)
+                metadata = self.__class__._db_meta.field_metadata
+                fields: set[str] = set()
+                for f in update_fields_set:
+                    meta = metadata.get(f)
+                    if meta is None:
+                        fields.add(f)
+                    elif meta.extra.get("reverse_fk") or meta.extra.get("m2m"):
+                        raise FieldError(
+                            f"'{f}' is a virtual relation field and cannot "
+                            f"be used in update_fields"
+                        )
+                    elif meta.foreign_key is not None:
+                        fields.add(meta.foreign_key.column_name)
+                    else:
+                        fields.add(f)
+            else:
+                fields = set(self.__class__.model_fields.keys())
+            if pk_field:
+                fields.discard(pk_field)
+            values = _dump_update_data(self, fields)
+            if not values:
+                # Call post_save even if no values to update (for consistency)
+                await self.post_save(
+                    is_create=is_create, update_fields=update_fields_set
+                )
+                return self
+
+            rows = await manager.filter(**{pk_field: pk_value}).update(  # type: ignore[misc]
+                returning=True, client=client, using=using, **values
+            )
+            if not rows:
+                cls_name = self.__class__.__name__
+                raise NotFoundError(f"{cls_name} with {pk_field}={pk_value} not found")
+            self.__dict__.update(rows[0].__dict__)
+        else:
+            created = await manager.create(
+                instance=self, client=client, using=using, _skip_hooks=True
+            )
+            self.__dict__.update(created.__dict__)
+
+        # Call post_save hook
+        await self.post_save(is_create=is_create, update_fields=update_fields_set)
+
+        return self
+
+    async def delete(
+        self,
+        *,
+        client: SupportsExecute | None = None,
+        using: str | None = None,
+    ) -> int:
+        manager = self.__class__.objects
+        pk_field = self.__class__._db_meta.pk_field
+        if not pk_field:
+            raise ManagerError("delete() requires a primary key")
+        pk_value = getattr(self, pk_field)
+        if pk_value is None:
+            raise ManagerError(
+                "delete() requires the instance to have a primary key value"
+            )
+
+        # Call pre_delete hook
+        await self.pre_delete()
+
+        # Use Manager.filter().delete() for deleting
+        affected = await manager.filter(**{pk_field: pk_value}).delete(
+            client=client, using=using
+        )
+
+        # Call post_delete hook
+        await self.post_delete()
+
+        return affected
+
+    async def refresh(
+        self,
+        *,
+        client: SupportsExecute | None = None,
+        using: str | None = None,
+    ) -> Self:
+        """
+        Reload this instance from the database.
+
+        Args:
+            client: Optional database client
+            using: Optional database alias
+
+        Returns:
+            Self with updated values
+
+        Raises:
+            ManagerError: If model has no primary key
+            NotFoundError: If instance not found in database
+
+        Examples:
+            user = await User.objects.get(id=42)
+            # ... time passes, data may have changed ...
+            await user.refresh()  # Reload from DB
+        """
+        pk_field = self.__class__._db_meta.pk_field
+        if not pk_field:
+            raise ManagerError("refresh() requires a primary key")
+        pk_value = getattr(self, pk_field)
+        if pk_value is None:
+            raise ManagerError(
+                "refresh() requires the instance to have a primary key value"
+            )
+
+        # Fetch fresh data from DB
+        refreshed = await self.__class__.objects.get(
+            client=client, using=using, **{pk_field: pk_value}
+        )
+
+        # Update all DB fields from the refreshed instance (skip virtual relations)
+        for field_name in type(self).model_fields:
+            meta = type(self)._db_meta.field_metadata.get(field_name)
+            if meta and (meta.extra.get("reverse_fk") or meta.extra.get("m2m")):
+                continue
+            setattr(self, field_name, getattr(refreshed, field_name))
+
+        return self
+
+
+__all__ = [
+    "Model",
+    "ModelMeta",
+    "ColumnMeta",
+    "ForeignKeyInfo",
+    "RelationInfo",
+    "RelationDescriptorBase",
+]