sqlmodel-ext 0.2.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

sqlmodel_ext/__init__.py

@@ -20,10 +20,10 @@ Quick start::
     user = await user.save(session)
     users = await User.get(session, fetch_mode="all")
 """
-__version__ = "0.2.0"
+__version__ = "0.2.1"
 
 # Base
-from sqlmodel_ext.base import SQLModelBase
+from sqlmodel_ext.base import SQLModelBase, ExtraIgnoreModelBase
 
 # Exceptions
 from sqlmodel_ext._exceptions import RecordNotFoundError
@@ -39,8 +39,11 @@ from sqlmodel_ext.pagination import (
 # Mixins
 from sqlmodel_ext.mixins import (
     # Table
+    SESSION_FOR_UPDATE_KEY,
     TableBaseMixin,
     UUIDTableBaseMixin,
+    rel,
+    cond,
     # Polymorphic
     PolymorphicBaseMixin,
     AutoPolymorphicIdentityMixin,
@@ -53,6 +56,9 @@ from sqlmodel_ext.mixins import (
     # Relation Preload
     RelationPreloadMixin,
     requires_relations,
+    requires_for_update,
+    # Cached Table
+    CachedTableBaseMixin,
     # Info Response DTOs
     IntIdInfoMixin,
     UUIDIdInfoMixin,
@@ -76,20 +82,28 @@ from sqlmodel_ext.field_types import (
     Str128,
     Str255,
     Str256,
+    Str500,
+    Str512,
+    Str2048,
     Text1K,
     Text1024,
     Text2K,
     Text2500,
     Text3K,
+    Text5K,
     Text10K,
     Text60K,
     Text64K,
     Text100K,
+    Text1M,
     # Numeric constraints
+    INT32_MAX,
     Port,
     Percentage,
     PositiveInt,
     NonNegativeInt,
+    PositiveBigInt,
+    NonNegativeBigInt,
     PositiveFloat,
     # Custom types
     IPAddress,
@@ -101,3 +115,12 @@ from sqlmodel_ext.field_types import (
     validate_not_private_host,
     ModuleNameMixin,
 )
+
+# Relation Load Checker (static analysis)
+from sqlmodel_ext.relation_load_checker import (
+    RelationLoadChecker,
+    RelationLoadWarning,
+    RelationLoadCheckMiddleware,
+    run_model_checks,
+    mark_app_check_completed,
+)

sqlmodel_ext/_sa_type.py

@@ -97,7 +97,8 @@ def _resolve_annotations(attrs: dict[str, Any]) -> tuple[
 
     try:
         temp_cls = type('AnnotationProxy', (object,), dict(attrs))
-        temp_cls.__module__ = module_name
+        if isinstance(module_name, str):
+            temp_cls.__module__ = module_name
         extras_kw = {'include_extras': True} if sys.version_info >= (3, 10) else {}
         evaluated = get_type_hints(
             temp_cls,
@@ -132,6 +133,6 @@ def _evaluate_annotation_from_string(
         return current_type
 
     try:
-        return eval(expr, globalns, localns)
+        return eval(expr, dict(globalns), dict(localns))
     except (NameError, SyntaxError, AttributeError, TypeError):
         return current_type

sqlmodel_ext/_utils.py

@@ -1,5 +1,5 @@
 """Internal utility functions."""
-from datetime import datetime
+from datetime import datetime, timezone
 
-now = lambda: datetime.now()
-now_date = lambda: datetime.now().date()
+now = lambda: datetime.now(timezone.utc)
+now_date = lambda: datetime.now(timezone.utc).date()

sqlmodel_ext/base.py

@@ -9,11 +9,13 @@ Provides a smart metaclass that handles:
 - Annotated sa_type extraction and injection
 - Python 3.14 (PEP 649) compatibility
 """
+import logging
+import re
 import sys
 import typing
 from typing import Any, get_args, get_origin
 
-from pydantic import ConfigDict
+from pydantic import ConfigDict, model_validator
 from pydantic.fields import FieldInfo
 from pydantic_core import PydanticUndefined as Undefined
 from sqlalchemy import inspect as sa_inspect
@@ -36,6 +38,61 @@ if sys.version_info >= (3, 14):
 else:
     annotationlib = None
 
+logger = logging.getLogger(__name__)
+
+
+def _make_sti_fk_resolver(
+    fk_string: str,
+    sa_registry: typing.Any,
+) -> typing.Callable:
+    """
+    Convert string-format foreign_keys to a callable for deferred resolution in STI.
+
+    STI child columns are added to the parent table via _register_sti_columns(),
+    but during configure_mappers() they are not yet registered as ColumnProperty.
+    SQLAlchemy's string resolution (_GetColumns.__getattr__) looks up columns via
+    mapper.all_orm_descriptors, which fails for unregistered STI columns.
+
+    Solution: convert to callable so configure_mappers() calls it to resolve
+    Column objects directly from the table's columns collection (Phase 1 already added them).
+
+    :param fk_string: String-format foreign_keys, e.g. '[NanoBananaFunction.flash_llm_id]'
+    :param sa_registry: SQLAlchemy registry for class-name lookup
+    :return: callable returning list of Column objects
+    """
+    inner = fk_string.strip('[]')
+    specs = [s.strip() for s in inner.split(',')]
+
+    parsed: list[tuple[str, str]] = []
+    for spec in specs:
+        m = re.match(r'^(\w+)\.(\w+)$', spec)
+        if not m:
+            return fk_string  # type: ignore  # cannot parse, return original
+        parsed.append((m.group(1), m.group(2)))
+
+    _registry = sa_registry
+
+    def _resolve() -> list:
+        columns = []
+        for cls_name, col_name in parsed:
+            for mapper in _registry.mappers:
+                if mapper.class_.__name__ == cls_name:
+                    table = mapper.local_table
+                    if col_name not in table.c:
+                        raise RuntimeError(
+                            f"STI FK resolution failed: column '{col_name}' "
+                            f"not in table '{table.name}' (class {cls_name})"
+                        )
+                    columns.append(table.c[col_name])
+                    break
+            else:
+                raise RuntimeError(
+                    f"STI FK resolution failed: class '{cls_name}' not in SA registry"
+                )
+        return columns
+
+    return _resolve
+
 
 class __DeclarativeMeta(SQLModelMetaclass):
     """
@@ -61,6 +118,13 @@ class __DeclarativeMeta(SQLModelMetaclass):
         if is_intended_as_table and 'table' not in kwargs:
             kwargs['table'] = True
 
+        # 1.5. CachedTableBaseMixin: cache_ttl class keyword -> __cache_ttl__ attribute
+        if 'cache_ttl' in kwargs:
+            ttl = kwargs.pop('cache_ttl')
+            if not isinstance(ttl, int) or ttl <= 0:
+                raise ValueError(f"{name}: cache_ttl must be a positive integer, got: {ttl!r}")
+            attrs['__cache_ttl__'] = ttl
+
         # 2. Detect STI scenario and preprocess
         parent_tablename = None
         for base in bases:
@@ -248,9 +312,21 @@ class __DeclarativeMeta(SQLModelMetaclass):
             return False
 
         if has_different_tablename and parent_tablename:
+            # JTI FK must also be primary_key (created by SubclassIdMixin).
+            # A FK pointing to the parent table that is NOT a PK (e.g. self-referential
+            # parent_transaction_id) should NOT be identified as JTI inheritance.
+            def _is_jti_fk(fi: typing.Any) -> bool:
+                fk = getattr(fi, 'foreign_key', None)
+                pk = getattr(fi, 'primary_key', None)
+                return (
+                    fk is not None
+                    and isinstance(fk, str)
+                    and pk is True  # PydanticUndefined is truthy, must compare strictly
+                    and _fk_matches_parent(fk, parent_tablename)
+                )
+
             for field_name, field_info in cls.model_fields.items():
-                fk = getattr(field_info, 'foreign_key', None)
-                if fk is not None and isinstance(fk, str) and _fk_matches_parent(fk, parent_tablename):
+                if _is_jti_fk(field_info):
                     has_fk_to_parent = True
                     break
 
@@ -258,8 +334,7 @@ class __DeclarativeMeta(SQLModelMetaclass):
                 for base in bases:
                     if hasattr(base, 'model_fields'):
                         for field_name, field_info in base.model_fields.items():
-                            fk = getattr(field_info, 'foreign_key', None)
-                            if fk is not None and isinstance(fk, str) and _fk_matches_parent(fk, parent_tablename):
+                            if _is_jti_fk(field_info):
                                 has_fk_to_parent = True
                                 break
                     if has_fk_to_parent:
@@ -367,73 +442,113 @@ class __DeclarativeMeta(SQLModelMetaclass):
                 mapper_args = getattr(cls, '__mapper_args__', {})
                 polymorphic_identity = mapper_args.get('polymorphic_identity')
 
-                if polymorphic_identity is not None:
-                    parent_cls = None
-                    for base in bases:
-                        if is_table_model_class(base) and hasattr(base, '__mapper__'):
-                            parent_cls = base
-                            break
+                # Support both concrete classes (polymorphic_identity set) and
+                # abstract intermediate classes (polymorphic_identity=None, polymorphic_abstract=True)
+                parent_cls = None
+                for base in bases:
+                    if is_table_model_class(base) and hasattr(base, '__mapper__'):
+                        parent_cls = base
+                        break
 
-                    if parent_cls is not None:
-                        registry = parent_cls._sa_registry
+                if parent_cls is not None:
+                    registry = parent_cls._sa_registry
 
-                        rels = getattr(cls, '__sqlmodel_relationships__', {})
-                        own_rels = {}
-                        for rel_name, rel_info in rels.items():
-                            is_inherited = any(
-                                hasattr(base, '__sqlmodel_relationships__') and rel_name in base.__sqlmodel_relationships__
-                                for base in bases
-                            )
-                            if not is_inherited:
-                                own_rels[rel_name] = rel_info
-
-                        properties = {}
-                        if own_rels:
-                            for rel_name, rel_info in own_rels.items():
-                                if rel_info.sa_relationship:
-                                    properties[rel_name] = rel_info.sa_relationship
-                                else:
-                                    raw_ann = cls.__annotations__.get(rel_name)
-                                    if raw_ann:
-                                        origin = get_origin(raw_ann)
-                                        if origin is Mapped:
-                                            ann = raw_ann.__args__[0]
-                                        else:
-                                            ann = raw_ann
-                                        relationship_to = get_relationship_to(
-                                            name=rel_name, rel_info=rel_info, annotation=ann
-                                        )
-                                        rel_kwargs: dict[str, typing.Any] = {}
-                                        if rel_info.back_populates:
-                                            rel_kwargs["back_populates"] = rel_info.back_populates
-                                        if rel_info.cascade_delete:
-                                            rel_kwargs["cascade"] = "all, delete-orphan"
-                                        if rel_info.passive_deletes:
-                                            rel_kwargs["passive_deletes"] = rel_info.passive_deletes
-                                        if rel_info.link_model:
-                                            ins = sa_inspect(rel_info.link_model)
-                                            local_table = getattr(ins, "local_table")
-                                            if local_table is None:
-                                                raise RuntimeError(
-                                                    f"Could not find secondary table for {rel_name}: {rel_info.link_model}"
-                                                )
-                                            rel_kwargs["secondary"] = local_table
-
-                                        rel_args: list[typing.Any] = []
-                                        if rel_info.sa_relationship_args:
-                                            rel_args.extend(rel_info.sa_relationship_args)
-                                        if rel_info.sa_relationship_kwargs:
-                                            rel_kwargs.update(rel_info.sa_relationship_kwargs)
-
-                                        properties[rel_name] = sa_relationship(relationship_to, *rel_args, **rel_kwargs)
-
-                        registry.map_imperatively(
-                            cls,
-                            parent_cls.__table__,
-                            inherits=parent_cls,
-                            polymorphic_identity=polymorphic_identity,
-                            properties=properties if properties else None,
+                    rels = getattr(cls, '__sqlmodel_relationships__', {})
+                    own_rels = {}
+                    for rel_name, rel_info in rels.items():
+                        is_inherited = any(
+                            hasattr(base, '__sqlmodel_relationships__') and rel_name in base.__sqlmodel_relationships__
+                            for base in bases
                         )
+                        if not is_inherited:
+                            own_rels[rel_name] = rel_info
+
+                    properties = {}
+                    if own_rels:
+                        for rel_name, rel_info in own_rels.items():
+                            if rel_info.sa_relationship:
+                                properties[rel_name] = rel_info.sa_relationship
+                            else:
+                                raw_ann = cls.__annotations__.get(rel_name)
+                                if raw_ann:
+                                    origin = get_origin(raw_ann)
+                                    if origin is Mapped:
+                                        ann = raw_ann.__args__[0]
+                                    else:
+                                        ann = raw_ann
+                                    relationship_to = get_relationship_to(
+                                        name=rel_name, rel_info=rel_info, annotation=ann
+                                    )
+                                    rel_kwargs: dict[str, typing.Any] = {}
+                                    if rel_info.back_populates:
+                                        rel_kwargs["back_populates"] = rel_info.back_populates
+                                    if rel_info.cascade_delete:
+                                        rel_kwargs["cascade"] = "all, delete-orphan"
+                                    if rel_info.passive_deletes:
+                                        rel_kwargs["passive_deletes"] = rel_info.passive_deletes
+                                    if rel_info.link_model:
+                                        ins = sa_inspect(rel_info.link_model)
+                                        local_table = getattr(ins, "local_table")
+                                        if local_table is None:
+                                            raise RuntimeError(
+                                                f"Could not find secondary table for {rel_name}: {rel_info.link_model}"
+                                            )
+                                        rel_kwargs["secondary"] = local_table
+
+                                    rel_args: list[typing.Any] = []
+                                    if rel_info.sa_relationship_args:
+                                        rel_args.extend(rel_info.sa_relationship_args)
+                                    if rel_info.sa_relationship_kwargs:
+                                        rel_kwargs.update(rel_info.sa_relationship_kwargs)
+
+                                    # Default lazy='raise_on_sql' for async safety:
+                                    # prevents accidental lazy-loading which causes
+                                    # MissingGreenlet errors in async environments.
+                                    if 'lazy' not in rel_kwargs:
+                                        rel_kwargs['lazy'] = 'raise_on_sql'
+
+                                    # STI foreign_keys deferred resolution:
+                                    # STI child columns are not yet registered as ColumnProperty
+                                    # during configure_mappers(), so string foreign_keys fail.
+                                    # Convert to callable for lazy resolution from table columns.
+                                    if 'foreign_keys' in rel_kwargs:
+                                        _fk_val = rel_kwargs['foreign_keys']
+                                        if isinstance(_fk_val, str):
+                                            rel_kwargs['foreign_keys'] = _make_sti_fk_resolver(
+                                                _fk_val, registry
+                                            )
+                                    else:
+                                        # Auto-detect FK ambiguity: when the "many" side STI child
+                                        # has a {rel_name}_id FK field but foreign_keys is not
+                                        # explicitly specified, add a callable to disambiguate.
+                                        _fk_field = f'{rel_name}_id'
+                                        _model_fields = getattr(cls, 'model_fields', None) or {}
+                                        if _fk_field in _model_fields:
+                                            _tbl = parent_cls.__table__
+                                            _fn = _fk_field
+                                            rel_kwargs['foreign_keys'] = (
+                                                lambda _t=_tbl, _f=_fn: [_t.c[_f]]
+                                            )
+
+                                    properties[rel_name] = sa_relationship(relationship_to, *rel_args, **rel_kwargs)
+
+                    # Build map_imperatively kwargs conditionally
+                    map_kwargs: dict[str, typing.Any] = {
+                        'inherits': parent_cls,
+                        'properties': properties if properties else None,
+                    }
+                    if polymorphic_identity is not None:
+                        map_kwargs['polymorphic_identity'] = polymorphic_identity
+                    # Abstract intermediate classes (e.g. TencentCompatibleLLM)
+                    # need polymorphic_abstract=True forwarded to map_imperatively
+                    if mapper_args.get('polymorphic_abstract'):
+                        map_kwargs['polymorphic_abstract'] = True
+
+                    registry.map_imperatively(
+                        cls,
+                        parent_cls.__table__,
+                        **map_kwargs,
+                    )
 
     def _setup_relationships(cls, only_these: set[str] | None = None) -> None:
         """
@@ -481,6 +596,11 @@ class __DeclarativeMeta(SQLModelMetaclass):
             if rel_info.sa_relationship_kwargs:
                 rel_kwargs.update(rel_info.sa_relationship_kwargs)
 
+            # Default lazy='raise_on_sql' for async safety: prevents accidental
+            # lazy-loading which causes MissingGreenlet errors in async environments.
+            if 'lazy' not in rel_kwargs:
+                rel_kwargs['lazy'] = 'raise_on_sql'
+
             rel_value = sa_relationship(relationship_to, *rel_args, **rel_kwargs)
             setattr(cls, rel_name, rel_value)
 
@@ -499,3 +619,53 @@ class SQLModelBase(SQLModel, metaclass=__DeclarativeMeta):
         """Get the set of computed_field names for this model class."""
         fields = cls.model_computed_fields
         return set(fields.keys()) if fields else set()
+
+
+class ExtraIgnoreModelBase(SQLModelBase):
+    """
+    Model base class that ignores unknown fields (extra='ignore').
+
+    Unlike SQLModelBase (extra='forbid'), this class silently ignores undeclared
+    fields and logs a WARNING for discoverability.
+
+    Use for:
+    - Third-party API responses (where the schema may change without notice)
+    - Client WebSocket message envelopes (protocol-level field validation)
+    - Any model parsing external JSON input (including nested sub-models)
+
+    Do NOT use for: request models that we construct and send to external services
+    (those should keep 'forbid' to catch mistakes).
+    """
+
+    model_config = ConfigDict(
+        use_attribute_docstrings=True, validate_by_name=True, extra='ignore',
+    )
+
+    @model_validator(mode='before')
+    @classmethod
+    def _warn_unknown_fields(cls, data: Any) -> Any:
+        """
+        Detect and warn about unknown fields in incoming data.
+
+        Logs a WARNING before Pydantic's extra='ignore' discards unknown fields,
+        helping developers notice third-party API changes and add field definitions.
+        """
+        if not isinstance(data, dict):
+            return data
+        accepted: set[str] = set()
+        for name, field_info in cls.model_fields.items():
+            accepted.add(name)
+            if field_info.alias:
+                accepted.add(field_info.alias)
+            if field_info.validation_alias and isinstance(field_info.validation_alias, str):
+                accepted.add(field_info.validation_alias)
+        unknown = set(data.keys()) - accepted
+        if unknown:
+            total = len(unknown)
+            sample = [name[:64] for name in sorted(unknown)[:5]]
+            logger.warning(
+                "External input contains unknown fields | model=%s "
+                "unknown_count=%d sample_fields=%s",
+                cls.__name__, total, sample,
+            )
+        return data

sqlmodel_ext/field_types/__init__.py

@@ -7,6 +7,8 @@ all compatible with Pydantic validation and SQLAlchemy column mapping.
 from pathlib import Path
 from typing import Annotated, TypeAlias
 
+from pydantic import StringConstraints
+from sqlalchemy import BigInteger
 from sqlmodel import Field
 
 from ._internal.path import _DirectoryPathHandler, _FilePathHandler
@@ -42,61 +44,79 @@ while behaving as a ``pathlib.Path`` in Python code.
 #  Field Constraint Type Aliases (Annotated Style)
 # ---------------------------------------------------------------------------
 
+_NO_NULL_BYTE = StringConstraints(pattern=r'^[^\x00]*$')
+"""PostgreSQL rejects null bytes in text columns. pydantic-core compiles the regex once with zero Python overhead."""
+
 # String length constraints
-Str24: TypeAlias = Annotated[str, Field(max_length=24)]
+Str24: TypeAlias = Annotated[str, Field(max_length=24), _NO_NULL_BYTE]
 """24-character string field"""
 
-Str32: TypeAlias = Annotated[str, Field(max_length=32)]
+Str32: TypeAlias = Annotated[str, Field(max_length=32), _NO_NULL_BYTE]
 """32-character string field"""
 
-Str36: TypeAlias = Annotated[str, Field(max_length=36)]
+Str36: TypeAlias = Annotated[str, Field(max_length=36), _NO_NULL_BYTE]
 """36-character string field (UUID standard format length)"""
 
-Str48: TypeAlias = Annotated[str, Field(max_length=48)]
+Str48: TypeAlias = Annotated[str, Field(max_length=48), _NO_NULL_BYTE]
 """48-character string field"""
 
-Str64: TypeAlias = Annotated[str, Field(max_length=64)]
+Str64: TypeAlias = Annotated[str, Field(max_length=64), _NO_NULL_BYTE]
 """64-character string field"""
 
-Str100: TypeAlias = Annotated[str, Field(max_length=100)]
+Str100: TypeAlias = Annotated[str, Field(max_length=100), _NO_NULL_BYTE]
 """100-character string field"""
 
-Str128: TypeAlias = Annotated[str, Field(max_length=128)]
+Str128: TypeAlias = Annotated[str, Field(max_length=128), _NO_NULL_BYTE]
 """128-character string field"""
 
-Str255: TypeAlias = Annotated[str, Field(max_length=255)]
+Str255: TypeAlias = Annotated[str, Field(max_length=255), _NO_NULL_BYTE]
 """255-character string field"""
 
-Str256: TypeAlias = Annotated[str, Field(max_length=256)]
+Str256: TypeAlias = Annotated[str, Field(max_length=256), _NO_NULL_BYTE]
 """256-character string field"""
 
-Text1K: TypeAlias = Annotated[str, Field(max_length=1000)]
+Str500: TypeAlias = Annotated[str, Field(max_length=500), _NO_NULL_BYTE]
+"""500-character string field"""
+
+Str512: TypeAlias = Annotated[str, Field(max_length=512), _NO_NULL_BYTE]
+"""512-character string field"""
+
+Str2048: TypeAlias = Annotated[str, Field(max_length=2048), _NO_NULL_BYTE]
+"""2048-character string field (URLs etc.)"""
+
+Text1K: TypeAlias = Annotated[str, Field(max_length=1000), _NO_NULL_BYTE]
 """1000-character text field"""
 
-Text1024: TypeAlias = Annotated[str, Field(max_length=1024)]
+Text1024: TypeAlias = Annotated[str, Field(max_length=1024), _NO_NULL_BYTE]
 """1024-character text field"""
 
-Text2K: TypeAlias = Annotated[str, Field(max_length=2000)]
+Text2K: TypeAlias = Annotated[str, Field(max_length=2000), _NO_NULL_BYTE]
 """2000-character text field"""
 
-Text2500: TypeAlias = Annotated[str, Field(max_length=2500)]
+Text2500: TypeAlias = Annotated[str, Field(max_length=2500), _NO_NULL_BYTE]
 """2500-character text field"""
 
-Text3K: TypeAlias = Annotated[str, Field(max_length=3000)]
+Text3K: TypeAlias = Annotated[str, Field(max_length=3000), _NO_NULL_BYTE]
 """3000-character text field"""
 
-Text10K: TypeAlias = Annotated[str, Field(max_length=10000)]
+Text5K: TypeAlias = Annotated[str, Field(max_length=5000), _NO_NULL_BYTE]
+"""5000-character text field"""
+
+Text10K: TypeAlias = Annotated[str, Field(max_length=10000), _NO_NULL_BYTE]
 """10000-character text field"""
 
-Text60K: TypeAlias = Annotated[str, Field(max_length=60000)]
+Text60K: TypeAlias = Annotated[str, Field(max_length=60000), _NO_NULL_BYTE]
 """60000-character text field"""
 
-Text64K: TypeAlias = Annotated[str, Field(max_length=65536)]
+Text64K: TypeAlias = Annotated[str, Field(max_length=65536), _NO_NULL_BYTE]
 """65536-character text field"""
 
-Text100K: TypeAlias = Annotated[str, Field(max_length=100000)]
+Text100K: TypeAlias = Annotated[str, Field(max_length=100000), _NO_NULL_BYTE]
 """100000-character text field"""
 
+Text1M: TypeAlias = Annotated[str, Field(max_length=1000000), _NO_NULL_BYTE]
+"""1000000-character text field (tool call parameters, tool responses, etc.)"""
+
 # Numeric range constraints
 Port: TypeAlias = Annotated[int, Field(ge=1, le=65535)]
 """Port number (1-65535)"""
@@ -104,11 +124,20 @@ Port: TypeAlias = Annotated[int, Field(ge=1, le=65535)]
 Percentage: TypeAlias = Annotated[int, Field(ge=0, le=100)]
 """Percentage (0-100)"""
 
-PositiveInt: TypeAlias = Annotated[int, Field(ge=1)]
-"""Positive integer (>=1)"""
+INT32_MAX = 2147483647
+"""Maximum value for PostgreSQL INTEGER column (2^31-1)"""
+
+PositiveInt: TypeAlias = Annotated[int, Field(ge=1, le=INT32_MAX)]
+"""Positive integer (1 to 2147483647, fits PostgreSQL INTEGER)"""
+
+NonNegativeInt: TypeAlias = Annotated[int, Field(ge=0, le=INT32_MAX)]
+"""Non-negative integer (0 to 2147483647, fits PostgreSQL INTEGER)"""
+
+PositiveBigInt: TypeAlias = Annotated[int, Field(ge=1, sa_type=BigInteger)]
+"""Positive big integer (>=1, BigInteger storage)"""
 
-NonNegativeInt: TypeAlias = Annotated[int, Field(ge=0)]
-"""Non-negative integer (>=0)"""
+NonNegativeBigInt: TypeAlias = Annotated[int, Field(ge=0, sa_type=BigInteger)]
+"""Non-negative big integer (>=0, BigInteger storage)"""
 
 PositiveFloat: TypeAlias = Annotated[float, Field(gt=0.0)]
 """Positive float (>0)"""