sqlmodel-ext 0.5.1__tar.gz → 0.5.2__tar.gz

{sqlmodel_ext-0.5.1 → sqlmodel_ext-0.5.2}/CHANGELOG.md

@@ -7,6 +7,57 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 > there is no stability or backward-compatibility guarantee between versions, and
 > you use it at your own risk. Pin the exact version you depend on.
 
+## [0.5.2]
+
+### Fixed
+
+- A table class field declared with a type alias and a plain right-hand value
+  (`x: NonNegativeDecimal38_18 = Decimal(0)`, `s: Str64 = 'a'`) had its default only in
+  `model_fields`: the JSON schema listed the field as `required` with no `default`, and
+  `model_validate({})` rejected the payload with "Field required". With an alias that
+  carries its own default (`opt: OptionalNonNegativeDecimal38_18 = Decimal(1)`),
+  `model_fields` even showed the alias's default (`None`) instead of the declared one.
+  The metaclass set the value on the field after constructing it, so Pydantic did not
+  count it as set when it built the core schema. A metaclass rebuild (an inherited field
+  description, a relationship) hid the defect in some classes. The same applied to a
+  field re-declared in the table class body without a right-hand side, which takes the
+  base's default. The table class now matches a non-table class with the same
+  declaration (schema, validation and `model_fields`). Non-table classes and fields the
+  table class inherits without re-declaring were not affected. Also present in 0.5.0
+  and 0.5.1.
+- **Behavior change.** A table class field declared with **several** `Field(...)` in one
+  `Annotated` and no right-hand side (`value: Legacy` with
+  `Legacy = Annotated[str, Field(alias='legacy', title='T'), Field(unique=True)]`, or a
+  nested alias such as `Annotated[Str64, Field(unique=True)]`) now gets its Pydantic
+  attributes as Pydantic merges them -- the same field a non-table class, plain
+  SQLModel and a table class inheriting the declaration already got. A later `Field`
+  overrides an earlier one, `None` included, and sqlmodel's `Field()` passes
+  `alias` / `validation_alias` / `serialization_alias` / `title` / `description` /
+  `default_factory` / `discriminator` / `exclude` explicitly as `None` and `repr` as
+  `True`. So when an earlier `Field` of the annotation sets any of these and a later
+  one does not, the table class no longer keeps the earlier value: the alias / title /
+  description are gone, and a `default_factory` is dropped, which makes the field
+  **required**. A `default` is not affected (sqlmodel's `Field()` does not pass it).
+  None of the bundled aliases combines several `Field`s or sets such an attribute. To keep the value, set it in the last `Field` or on a right-hand
+  `= Field(...)`. The same holds for a non-table class whose field needs an injected
+  `sa_type` (`Annotated[FilePathType, Field(alias='p'), Field(index=True)]`), which kept
+  the earlier `alias` too. The same path also applied the `Field` of an alias nested in a
+  union with no right-hand side, which Pydantic does not merge at field level:
+  `x: OptionalNonNegativeDecimal38_18 | None` declared in a table class had
+  `default=None`; it is now **required**, as it already was in a non-table class, when
+  inherited, and with a right-hand `Field` that sets no default (0.5.1). Drop the
+  redundant `| None` or write `= None`. The column attributes of all the declaration's `Field`s are
+  still folded into the column, now with the precedence Pydantic uses for the Pydantic
+  attributes: the right-hand `Field` first, then the annotation's `Field`s from the last
+  to the first; `False` still never switches off `True`. So a table class **inheriting**
+  such a declaration agrees with one declaring it directly:
+  `Annotated[NonNegativeDecimal38_18, Field(sa_type=Numeric(20, 2))]` gives
+  `NUMERIC(20, 2)` in both (inheriting it gave `NUMERIC(38, 18)`, the alias's
+  `sa_type`). Plain SQLModel, which reads only the first carrier, still gives
+  `NUMERIC(38, 18)`. Also present in 0.5.0 and 0.5.1. This only changes the metadata
+  the models build: existing databases are not altered. Tables created from now on
+  (`create_all`) get the new column type; to align an existing table, write a migration.
+
 ## [0.5.1]
 
 ### Added

{sqlmodel_ext-0.5.1 → sqlmodel_ext-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sqlmodel-ext
-Version: 0.5.1
+Version: 0.5.2
 Summary: Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphic inheritance, optimistic locking, relation preloading, and reusable field types.
 Project-URL: Homepage, https://github.com/Foxerine/sqlmodel-ext
 Project-URL: Repository, https://github.com/Foxerine/sqlmodel-ext

{sqlmodel_ext-0.5.1 → sqlmodel_ext-0.5.2}/docs/en/explanation/metaclass.md

@@ -142,7 +142,7 @@ This snapshot must be taken **before** any annotation injection: later steps inj
 
 ### Step 4.5: Recover SQLModel attributes from `Annotated[T, Field(...)]`
 
-When Pydantic v2 processes `Annotated` metadata it replaces `sqlmodel.main.FieldInfo` with `pydantic.fields.FieldInfo`, which knows nothing about SQLModel attributes such as `foreign_key` or `sa_type`. For **table classes** (including `Annotated` fields inherited from parents), `_recover_annotated_sqlmodel_fields()` converts them back into the `= Field(...)` form; non-table classes are left as-is so child table classes can inherit them. When several `FieldInfo`s are merged, an explicit `default=None` is kept as a real value (not "unset") — otherwise the field would silently become required. A field with a right-hand `Field` (`name: Alias = Field(...)`) is rebuilt from Pydantic's resolution of that declaration — `FieldInfo.from_annotated_attribute()` when the table class declares it, the base's resolved field `Base.model_fields[name]` when the table class **inherits** it (without re-declaring it). Both give the same field: its Pydantic attributes are taken as-is (an explicit `alias=None` stays `None`, as in plain SQLModel), and only the column attributes are completed — the `FieldInfoMetadata` carriers of the alias's and the right-hand `Field` are folded into one, since SQLModel reads only the first. Metadata that stays in the class annotation (an `AfterValidator` next to the alias's `Field`, for example) is not copied into the field, so it is applied once.
+When Pydantic v2 processes `Annotated` metadata it replaces `sqlmodel.main.FieldInfo` with `pydantic.fields.FieldInfo`, which knows nothing about SQLModel attributes such as `foreign_key` or `sa_type`. For **table classes** (including `Annotated` fields inherited from parents), `_recover_annotated_sqlmodel_fields()` converts them back into the `= Field(...)` form; non-table classes are left as-is so child table classes can inherit them. Every such field is rebuilt from **Pydantic's own resolution of its declaration** — the field a non-table class (or plain SQLModel) gets for the same declaration: `FieldInfo.from_annotated_attribute()` when the table class declares it with a right-hand side (`= Field(...)` or a plain value such as `= 'a'`), `FieldInfo.from_annotation()` when it declares it without one, and the base's resolved field `Base.model_fields[name]` when the table class **inherits** it (without re-declaring it). Its Pydantic attributes are taken as-is. Several `Field`s in one `Annotated` merge as Pydantic merges them: a later `Field` overrides an earlier one, `None` included — sqlmodel's `Field()` passes `alias` / `validation_alias` / `serialization_alias` / `title` / `description` / `default_factory` / `discriminator` / `exclude` explicitly as `None` (and `repr` as `True`), so `Annotated[str, Field(alias='a', title='T'), Field(unique=True)]` has neither alias nor title; a right-hand `Field` overrides them all. The `Field` of an alias nested in a union (`OptionalNonNegativeDecimal38_18 | None`) is not merged at field level, so its `default=None` does not apply — only its constraints and column attributes are carried over. The attributes are passed to the constructor, so Pydantic records them as set and they reach the core schema: a default of `x: Str64 = 'a'` is in the JSON schema and in validation, not only in `model_fields`. Only the column attributes are completed — the `FieldInfoMetadata` carriers of all the declaration's `Field`s are folded into one, since SQLModel reads only the first: the right-hand `Field`'s first, then the annotation's from the last to the first (`Annotated[NonNegativeDecimal38_18, Field(sa_type=Numeric(20, 2))]` gets `NUMERIC(20, 2)`), and `False` never switches off `True`. One library rule departs from Pydantic: a field re-declared in the table class body without a right-hand side keeps the base's default (Pydantic would make it required). Metadata that stays in the class annotation (an `AfterValidator` next to the alias's `Field`, for example) is not copied into the field, so it is applied once.
 
 ### Step 4.5.b: `oplock_version` is a reserved name
 
@@ -182,8 +182,8 @@ for field_name, field_type in annotations.items():
     if sa_type is not None:
         field_value = attrs.get(field_name, Undefined)
         if field_value is Undefined:
-            # no "= Field(...)": prefer recovering the user's FieldInfo from inside Annotated,
-            # keeping default_factory / max_length etc., and only add sa_type
+            # no "= Field(...)": a right-hand Field carrying Pydantic's own resolution of the
+            # Annotated (default_factory etc. kept, nothing changed) plus sa_type
             annotated_fi = _find_field_info_in_annotated(field_type)
             attrs[field_name] = annotated_fi if annotated_fi is not None else Field(sa_type=sa_type)
         elif isinstance(field_value, FieldInfo):
@@ -218,7 +218,7 @@ result = super().__new__(cls, name, bases, attrs, **kwargs)
 #         merge the saved SQLModelFieldInfo back and rebuild the Column
 ```
 
-While merging, boolean flags are never overwritten with `False` (`unique=False` never switches off an inherited `unique=True`), and `FieldInfoMetadata` carriers are folded into one (SQLModel reads only the first; otherwise an all-unset carrier inside a type alias shadows `= Field(primary_key=True)` — which is exactly why `id: NonNegativeInt = Field(primary_key=True)` lost its primary key on sqlmodel ≥ 0.0.32).
+Step 7 only copies back what Pydantic filled in; there `None` and `False` never overwrite a saved value. The `FieldInfoMetadata` carriers of one declaration were already folded into one in step 4.5 (SQLModel reads only the first; otherwise an all-unset carrier inside a type alias shadows `= Field(primary_key=True)` — which is exactly why `id: NonNegativeInt = Field(primary_key=True)` lost its primary key on sqlmodel ≥ 0.0.32).
 
 ### Steps 8–9: Relationship fields under inheritance
 

{sqlmodel_ext-0.5.1 → sqlmodel_ext-0.5.2}/docs/explanation/metaclass.md

@@ -142,7 +142,7 @@ _own_annotation_names = frozenset(annotations)
 
 ### 第 4.5 步：恢复 `Annotated[T, Field(...)]` 中的 SQLModel 属性
 
-Pydantic v2 处理 `Annotated` 元数据时会把 `sqlmodel.main.FieldInfo` 换成 `pydantic.fields.FieldInfo`，后者不认识 `foreign_key`、`sa_type` 等 SQLModel 属性。`_recover_annotated_sqlmodel_fields()` 对 **table 类**（包括从父类继承来的 `Annotated` 字段）把它们还原成 `= Field(...)` 形式；非 table 类保留原样，供子 table 类继承。合并多个 `FieldInfo` 时，显式的 `default=None` 被当作真实的值（而不是"未设置"）保留——否则字段会静默变成必填。带右侧 `Field` 的字段（`name: Alias = Field(...)`）以 Pydantic 对该声明的解析结果为准重建——table 类自己声明时用 `FieldInfo.from_annotated_attribute()`，table 类**继承**（未在类体里重新声明）时用基类已解析的字段 `Base.model_fields[name]`。两者得到同一个字段：Pydantic 层属性原样采用（显式的 `alias=None` 仍是 `None`，与纯 SQLModel 一致），只补全列属性——别名的 `Field` 与右侧 `Field` 各自的 `FieldInfoMetadata` 载体被折叠成一个，因为 SQLModel 只读第一个。仍留在类注解里的元数据（例如与别名 `Field` 并列的 `AfterValidator`）不会再复制进字段，因此只执行一次。
+Pydantic v2 处理 `Annotated` 元数据时会把 `sqlmodel.main.FieldInfo` 换成 `pydantic.fields.FieldInfo`，后者不认识 `foreign_key`、`sa_type` 等 SQLModel 属性。`_recover_annotated_sqlmodel_fields()` 对 **table 类**（包括从父类继承来的 `Annotated` 字段）把它们还原成 `= Field(...)` 形式；非 table 类保留原样，供子 table 类继承。每个这样的字段都以 **Pydantic 对该声明自己的解析结果**为准重建——也就是同一份声明写在非 table 类（或纯 SQLModel）里得到的字段：table 类自己声明且带右侧值（`= Field(...)` 或 `= 'a'` 这样的普通值）时用 `FieldInfo.from_annotated_attribute()`，自己声明但没有右侧值时用 `FieldInfo.from_annotation()`，table 类**继承**（未在类体里重新声明）时用基类已解析的字段 `Base.model_fields[name]`。Pydantic 层属性原样采用。同一个 `Annotated` 里的多个 `Field` 按 Pydantic 的规则合并：后一个 `Field` 覆盖前一个，`None` 也算——sqlmodel 的 `Field()` 会把 `alias` / `validation_alias` / `serialization_alias` / `title` / `description` / `default_factory` / `discriminator` / `exclude` 显式传成 `None`（`repr` 传成 `True`），所以 `Annotated[str, Field(alias='a', title='T'), Field(unique=True)]` 既没有 alias 也没有 title；右侧 `Field` 覆盖它们全部。嵌在联合类型里的别名（`OptionalNonNegativeDecimal38_18 | None`）的 `Field` 不在字段层合并，所以它的 `default=None` 不生效——只带过来它的约束与列属性。这些属性经构造函数传入，Pydantic 把它们记为"已设置"，于是能进入 core schema：`x: Str64 = 'a'` 的默认值会出现在 JSON schema 与校验里，而不只是在 `model_fields` 里。只补全列属性——声明中所有 `Field` 的 `FieldInfoMetadata` 载体被折叠成一个，因为 SQLModel 只读第一个：先右侧 `Field` 的，再按注解里从后往前的顺序（`Annotated[NonNegativeDecimal38_18, Field(sa_type=Numeric(20, 2))]` 得到 `NUMERIC(20, 2)`），且 `False` 不会关掉 `True`。有一条本库规则与 Pydantic 不同：在 table 类体里重新声明、但没有右侧值的字段，沿用基类的默认值（Pydantic 会让它变成必填）。仍留在类注解里的元数据（例如与别名 `Field` 并列的 `AfterValidator`）不会再复制进字段，因此只执行一次。
 
 ### 第 4.5.b 步：`oplock_version` 是保留名
 
@@ -182,8 +182,8 @@ for field_name, field_type in annotations.items():
     if sa_type is not None:
         field_value = attrs.get(field_name, Undefined)
         if field_value is Undefined:
-            # 没有 "= Field(...)"：优先从 Annotated 里取回用户的 FieldInfo，
-            # 保住 default_factory / max_length 等，只把 sa_type 加进去
+            # 没有 "= Field(...)"：造一个携带 Pydantic 对该 Annotated 自身解析结果的右侧 Field
+            # （default_factory 等原样保住，不改变任何东西），再把 sa_type 加进去
             annotated_fi = _find_field_info_in_annotated(field_type)
             attrs[field_name] = annotated_fi if annotated_fi is not None else Field(sa_type=sa_type)
         elif isinstance(field_value, FieldInfo):
@@ -218,7 +218,7 @@ result = super().__new__(cls, name, bases, attrs, **kwargs)
 #         用保存的 SQLModelFieldInfo 合并回去并重建 Column
 ```
 
-合并时，布尔标志不会被 `False` 覆盖（`unique=False` 不会关掉继承来的 `unique=True`），`FieldInfoMetadata` 载体会被折叠成一个（SQLModel 只读第一个；否则类型别名里全空的载体会遮住 `= Field(primary_key=True)`——这正是 sqlmodel ≥ 0.0.32 上 `id: NonNegativeInt = Field(primary_key=True)` 丢失主键的原因）。
+第 7 步只把 Pydantic 填上的值拷回来，此处 `None` 与 `False` 不会覆盖已保存的值。同一声明的 `FieldInfoMetadata` 载体在第 4.5 步已折叠成一个（SQLModel 只读第一个；否则类型别名里全空的载体会遮住 `= Field(primary_key=True)`——这正是 sqlmodel ≥ 0.0.32 上 `id: NonNegativeInt = Field(primary_key=True)` 丢失主键的原因）。
 
 ### 第 8–9 步：继承中的关系字段
 

{sqlmodel_ext-0.5.1 → sqlmodel_ext-0.5.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sqlmodel-ext"
-version = "0.5.1"
+version = "0.5.2"
 description = "Extended SQLModel infrastructure: smart metaclass, async CRUD mixins, polymorphic inheritance, optimistic locking, relation preloading, and reusable field types."
 readme = "README.md"
 license = "MIT"

{sqlmodel_ext-0.5.1 → sqlmodel_ext-0.5.2}/src/sqlmodel_ext/__init__.py

@@ -20,7 +20,7 @@ Quick start::
     user = await user.save(session)
     users = await User.get(session, fetch_mode="all")
 """
-__version__ = "0.5.1"
+__version__ = "0.5.2"
 
 # Every re-export below uses the redundant ``X as X`` form: the package ships
 # ``py.typed``, and type checkers treat a plain ``from m import X`` in a typed

{sqlmodel_ext-0.5.1 → sqlmodel_ext-0.5.2}/src/sqlmodel_ext/base.py

@@ -129,11 +129,13 @@ def _merge_field_info_attrs(target: SQLModelFieldInfo, source: FieldInfo) -> Non
     """
     Merge explicitly-set attributes from ``source`` into ``target``.
 
-    Used when ``Annotated[Str64, Field(unique=True)]`` expands to multiple FieldInfo:
-    ``Annotated[str, Field(max_length=64), Field(unique=True)]``, and to restore the
-    SQLModel attributes Pydantic drops when it rebuilds ``model_fields``. A
-    right-hand-side ``= Field(...)`` is not merged here: it follows Pydantic's
-    resolution, ``None`` included (see ``_inherit_resolved_field``).
+    Only used by the metaclass's final restore step (step 7), where ``source``
+    is the field Pydantic built **from** ``target`` and ``target`` gets back
+    the values Pydantic filled in; there ``None`` never means "cleared", so
+    skipping it is correct. It is **not** a field-declaration merge: the
+    ``Field(...)`` objects of one declaration (several ``Field`` in one
+    ``Annotated``, an alias plus a right-hand ``= Field(...)``) follow
+    Pydantic's resolution, ``None`` included (see ``_inherit_resolved_field``).
     Merges attributes dynamically (via ``__slots__`` / ``__annotations__`` / ``__dict__``),
     no hardcoded attribute names — upstream additions are handled automatically.
 
@@ -205,10 +207,10 @@ def _merge_sqlmodel_metadata_carrier(
     Since sqlmodel 0.0.32, ``Field(primary_key=..., sa_type=..., ...)`` stores the
     SQLModel-specific attributes in a ``FieldInfoMetadata`` entry of
     ``metadata``, and SQLModel reads only the **first** such entry. Plain
-    concatenation would therefore let an earlier, all-unset carrier (e.g. the
-    one inside a constrained alias like ``NonNegativeInt``) shadow the values
-    set by the later, more specific source (e.g. a right-hand
-    ``= Field(primary_key=True)``).
+    concatenation would therefore let an earlier, all-unset carrier shadow the
+    values set by the later source. Only ``_merge_field_info_attrs`` (the
+    metaclass's restore step) uses it; the carriers of one field declaration
+    are folded by ``_fold_column_carriers``.
 
     Set values of the source carrier are folded into a **copy** of the target
     carrier (carriers inside type aliases are shared singletons and must not be
@@ -248,7 +250,7 @@ Public Pydantic ``FieldInfo`` attributes an inherited field takes verbatim from
 
 
 def _inherit_resolved_field(
-        alias_fi: SQLModelFieldInfo,
+        alias_fis: list[SQLModelFieldInfo],
         base_fi: FieldInfo,
         annotation_metadata: list[Any],
 ) -> SQLModelFieldInfo:
@@ -256,81 +258,91 @@ def _inherit_resolved_field(
     Build the ``FieldInfo`` of a table-class field from Pydantic's resolution of its declaration.
 
     ``base_fi`` is the field as Pydantic resolves the declaration
-    ``name: Alias = Field(...)``: the base class's entry in ``model_fields``
-    for an inherited field, ``FieldInfo.from_annotated_attribute`` for a
-    declaration in the table class itself. Pydantic has merged the type
-    alias's ``Field(...)`` and the right-hand ``= Field(...)`` into it. It is
-    the single source of truth for the field:
+    ``name: Alias [= value]``: the base class's entry in ``model_fields`` for
+    an inherited field; ``FieldInfo.from_annotated_attribute`` for a
+    declaration with a right-hand side (``= Field(...)`` or a plain value) in
+    the table class itself; ``FieldInfo.from_annotation`` for one without.
+    Pydantic has merged every ``Field(...)`` of the declaration into it -- the
+    ones inside the ``Annotated`` (later ones override earlier ones, ``None``
+    included) and the right-hand one (which overrides them all). ``alias_fis``
+    are the SQLModel ``Field(...)`` objects found in the annotation, in
+    declaration order. ``base_fi`` is the single source of truth for the field:
 
     - **Pydantic attributes** (``default`` / ``default_factory`` / ``alias`` /
       ``validation_alias`` / ``serialization_alias`` / ``title`` /
       ``description`` / ``examples`` / ``exclude`` / ``frozen`` / ...) are
       taken from ``base_fi`` verbatim, ``None`` included: ``Field(alias=None)``
-      in the base clears the alias's ``alias`` and the table class must see
-      the same field as the base does. They are passed to the constructor so
-      that Pydantic records every one of them as explicitly set -- the same
+      clears an earlier ``alias`` and the table class must see the same field
+      as a non-table class does. They are passed to the constructor so that
+      Pydantic records every one of them as explicitly set -- the same
       treatment Pydantic gives a resolved ``FieldInfo`` reused as a default.
+      Setting them afterwards (``fi.default = value``) would not record them:
+      Pydantic would then drop them when it builds the field and its core
+      schema, while ``model_fields`` (restored by the metaclass) keeps them.
     - **Metadata** starts from ``base_fi.metadata`` minus ``annotation_metadata``:
       the metadata Pydantic collects from the rebuilt class annotation (the
       ``Annotated`` arguments other than the SQLModel ``Field``, e.g. an
       ``AfterValidator``). Pydantic adds those again when it builds the
       field, so keeping them here would run such a validator twice. Each
-      annotation item removes one equal item. Items of ``alias_fi.metadata``
-      whose type ``base_fi`` lacks are appended: an alias nested in a union
-      (``Alias | None = Field(...)``) is not merged by Pydantic at field level,
-      so its constraints (``MaxLen`` -> column length) and column carrier are
-      absent from ``base_fi``.
+      annotation item removes one equal item. Items of the ``alias_fis``
+      metadata whose type ``base_fi`` lacks are appended: an alias nested in a
+      union (``Alias | None``) is not merged by Pydantic at field level, so its
+      constraints (``MaxLen`` -> column length) are absent from ``base_fi``.
     - **Column attributes**: SQLModel reads only the first ``FieldInfoMetadata``
-      carrier, while ``base_fi`` holds one per ``Field(...)`` -- the right-hand
-      one first. All carriers are folded into one (see
-      ``_fold_column_carriers``) and the folded values are also set as
-      instance attributes for readers using ``getattr(field, 'primary_key')``.
-
-    ``alias_fi`` is not mutated.
+      carrier. All carriers of the declaration are folded into one (see
+      ``_fold_column_carriers``), by the precedence Pydantic applies to the
+      Pydantic attributes: the carriers of ``base_fi`` that are not the
+      annotation's (those of the right-hand ``Field``) first, then the
+      annotation's from the last ``Field`` to the first. The folded values
+      are also set as instance attributes for readers using
+      ``getattr(field, 'primary_key')``.
+
+    Neither ``alias_fis`` nor their carriers are mutated.
     """
     kwargs: dict[str, Any] = {name: getattr(base_fi, name) for name in _PYDANTIC_FIELD_ATTRS}
     inherited = SQLModelFieldInfo(**kwargs)
 
+    alias_meta = [item for alias_fi in alias_fis for item in alias_fi.metadata]
+    alias_carriers = [item for item in alias_meta if isinstance(item, FieldInfoMetadata)]
+    base_types = {type(item) for item in base_fi.metadata}
     base_meta = list(base_fi.metadata)
     for item in annotation_metadata:
         base_meta.remove(item)
-    base_types = {type(item) for item in base_meta}
-    alias_extra = [
-        item for item in alias_fi.metadata
-        if isinstance(item, FieldInfoMetadata) or type(item) not in base_types
+    right_hand_carriers = [
+        item for item in base_meta
+        if isinstance(item, FieldInfoMetadata) and not any(item is c for c in alias_carriers)
     ]
-    metadata = _fold_column_carriers(base_meta + alias_extra)
-    inherited.metadata = metadata
-
-    carrier = next((m for m in metadata if isinstance(m, FieldInfoMetadata)), None)
+    metadata = [item for item in base_meta if not isinstance(item, FieldInfoMetadata)]
+    metadata += [
+        item for item in alias_meta
+        if not isinstance(item, FieldInfoMetadata) and type(item) not in base_types
+    ]
+    carrier = _fold_column_carriers(right_hand_carriers + alias_carriers[::-1])
     if carrier is not None:
+        metadata.append(carrier)
         for fim_field in dataclasses.fields(carrier):
             value = getattr(carrier, fim_field.name)
             if value is not _FIM_UNSET_SA_TYPE:
                 setattr(inherited, fim_field.name, value)
+    inherited.metadata = metadata
     return inherited
 
 
-def _fold_column_carriers(metadata: list[Any]) -> list[Any]:
+def _fold_column_carriers(carriers: list[FieldInfoMetadata]) -> FieldInfoMetadata | None:
     """
-    Fold every ``FieldInfoMetadata`` carrier of ``metadata`` into the first one.
-
-    Carriers are ordered by precedence: an earlier carrier's set value wins; a
-    later carrier only fills attributes the earlier ones left unset -- except
-    that ``True`` replaces an earlier ``False`` (the rule
-    ``_merge_field_info_attrs`` applies to boolean flags, so ``unique=False`` on
-    the right-hand side never switches off ``unique=True`` from the alias).
-    The first carrier is replaced by a folded **copy** (carriers inside type
-    aliases are shared); the others are dropped. Non-carrier items are kept
-    unchanged and in order.
+    Fold ``FieldInfoMetadata`` carriers, ordered by precedence, into a new one.
+
+    An earlier carrier's set value wins; a later carrier only fills attributes
+    the earlier ones left unset -- except that ``True`` replaces an earlier
+    ``False``, so ``unique=False`` never switches off ``unique=True`` set
+    elsewhere in the declaration. The result is always a **copy** (carriers
+    inside type aliases are shared singletons and are later written to, e.g.
+    by ``_durably_set_sa_type``). ``None`` when there is no carrier.
     """
-    carrier_indexes = [i for i, m in enumerate(metadata) if isinstance(m, FieldInfoMetadata)]
-    if len(carrier_indexes) < 2:
-        return list(metadata)
-    first = carrier_indexes[0]
-    folded = copy.copy(metadata[first])
-    for index in carrier_indexes[1:]:
-        later = metadata[index]
+    if not carriers:
+        return None
+    folded = copy.copy(carriers[0])
+    for later in carriers[1:]:
         for fim_field in dataclasses.fields(later):
             value = getattr(later, fim_field.name)
             if value is _FIM_UNSET_SA_TYPE:
@@ -338,49 +350,46 @@ def _fold_column_carriers(metadata: list[Any]) -> list[Any]:
             current = getattr(folded, fim_field.name)
             if current is _FIM_UNSET_SA_TYPE or (current is False and value is True):
                 setattr(folded, fim_field.name, value)
-    dropped = frozenset(carrier_indexes[1:])
-    return [folded if i == first else m for i, m in enumerate(metadata) if i not in dropped]
+    return folded
 
 
 def _find_field_info_in_annotated(annotation: Any) -> SQLModelFieldInfo | None:
     """
-    Extract SQLModel ``FieldInfo`` embedded in ``Annotated[T, Field(...)]`` metadata.
+    Build a right-hand ``Field`` for ``Annotated[T, Field(...)]`` that changes nothing Pydantic resolves.
 
     Used by the metaclass sa_type injection loop. When a field is declared
     ``Annotated[X, Field(default_factory=list, ...)]`` *without* an explicit
     ``= ...`` assignment, ``attrs[field_name]`` is ``Undefined``. Replacing
     it with a fresh ``Field(sa_type=sa_type)`` would discard the user's
     Field metadata (``default_factory``, ``max_length``, validators, ...)
-    that lives inside the Annotated args. This helper recovers that
-    FieldInfo so the caller can attach ``sa_type`` to the user's Field
-    instead of clobbering it. The bug only surfaces after 2+ levels of
-    inheritance: single-class instantiation goes through Pydantic's native
-    Annotated path and works, but child classes rebuild ``model_fields``
-    from the clobbered ``attrs`` and the field becomes silently
-    ``is_required=True``.
-
-    Multiple FieldInfo args (e.g. ``Annotated[Str64, Field(unique=True)]``
-    expands to ``Annotated[str, Field(max_length=64), Field(unique=True)]``)
-    are merged into a single shallow copy so the shared Annotated metadata
-    singletons are never mutated.
+    that lives inside the Annotated args. The bug only surfaces after 2+
+    levels of inheritance: single-class instantiation goes through
+    Pydantic's native Annotated path and works, but child classes rebuild
+    ``model_fields`` from the clobbered ``attrs`` and the field becomes
+    silently ``is_required=True``.
+
+    The returned field carries Pydantic's own resolution of the annotation
+    (every ``Field`` in it merged, later ones overriding earlier ones,
+    ``None`` included) with every Pydantic attribute explicitly set, so
+    Pydantic, merging it back in as the right-hand side, gets the same field
+    as without it. Its only metadata is the folded column carrier, to which
+    the caller attaches ``sa_type``; the annotation's constraints stay in the
+    annotation. Reached for non-table classes only: a table class's
+    annotation has already been stripped of its SQLModel ``Field``s by
+    ``_recover_annotated_sqlmodel_fields``.
 
     :param annotation: Field type annotation
-    :returns: Merged SQLModelFieldInfo (shallow copy, safe to mutate), or None
+    :returns: A new SQLModelFieldInfo (safe to mutate), or None
     """
     if get_origin(annotation) is not typing.Annotated:
         return None
-    args = get_args(annotation)
-    if len(args) < 2:
-        return None
     sqlmodel_fis: list[SQLModelFieldInfo] = [
-        arg for arg in args[1:] if isinstance(arg, SQLModelFieldInfo)
+        arg for arg in get_args(annotation)[1:] if isinstance(arg, SQLModelFieldInfo)
     ]
     if not sqlmodel_fis:
         return None
-    merged = copy.copy(sqlmodel_fis[0])
-    for extra_fi in sqlmodel_fis[1:]:
-        _merge_field_info_attrs(merged, extra_fi)
-    return merged
+    resolved = FieldInfo.from_annotation(annotation)
+    return _inherit_resolved_field(sqlmodel_fis, resolved, list(resolved.metadata))
 
 
 def _durably_set_sa_type(field_info: Any, sa_type: Any) -> None:
@@ -835,12 +844,6 @@ def _recover_annotated_sqlmodel_fields(
         if not sqlmodel_fis:
             continue
 
-        # Merge multiple FieldInfo: shallow-copy first then merge to avoid mutating
-        # shared Annotated metadata singletons (e.g. Str64 = Annotated[str, Field(max_length=64)])
-        sqlmodel_fi = copy.copy(sqlmodel_fis[0])
-        for extra_fi in sqlmodel_fis[1:]:
-            _merge_field_info_attrs(sqlmodel_fi, extra_fi)
-
         # The class annotation without the SQLModel FieldInfo; any other
         # ``Annotated`` metadata (validators, serializers, ...) stays in it.
         base_type = args[0]
@@ -864,62 +867,48 @@ def _recover_annotated_sqlmodel_fields(
         else:
             rebuilt = new_inner
 
-        # Transfer plain defaults from attrs (e.g. = 0, = None) to FieldInfo
+        # The field is rebuilt from Pydantic's resolution of the declaration --
+        # the same ``FieldInfo`` a non-table class gets for it (see
+        # ``_inherit_resolved_field``): its Pydantic attributes follow that
+        # resolution, ``None`` included; only the column attributes of every
+        # ``Field`` of the declaration are folded together.
         existing_default = attrs.get(field_name, Undefined)
-        if existing_default is not Undefined and not isinstance(existing_default, (FieldInfo, SQLModelFieldInfo)):
-            sqlmodel_fi.default = existing_default
-        elif isinstance(existing_default, (FieldInfo, SQLModelFieldInfo)):
-            # A right-hand-side ``= Field(...)`` coexists with the FieldInfo inside
-            # the annotation, e.g.
-            # ``value: NonNegativeBigInt | None = Field(default=None, sa_type=BigInteger)``.
-            # Without this branch the right-hand FieldInfo would be discarded
-            # (overwritten by ``attrs[field_name] = sqlmodel_fi`` below) and an
-            # explicit ``default=None`` would vanish, silently making the field
-            # required.
-            #
-            # Pydantic resolves the declaration exactly as it does for a
-            # non-table class (``from_annotated_attribute`` is the step that
-            # builds ``model_fields`` entries), so the field is then treated like
-            # an inherited one: its Pydantic attributes follow that resolution,
-            # ``None`` included (``Field(alias=None)`` clears the alias's
-            # ``alias``, as in plain SQLModel and in a table class inheriting
-            # the same declaration); only the column attributes of the alias
-            # and the right-hand ``Field`` are folded together (see
-            # ``_inherit_resolved_field``).
+        base_fi = next(
+            (
+                base_fields[field_name]
+                for base in bases
+                if (base_fields := getattr(base, 'model_fields', None)) and field_name in base_fields
+            ),
+            None,
+        )
+        if existing_default is not Undefined:
+            # A right-hand side in the class body: ``= Field(...)`` or a plain
+            # value (``= 0``, ``= None``). ``from_annotated_attribute`` is the
+            # step Pydantic uses to build ``model_fields`` entries.
             resolved = FieldInfo.from_annotated_attribute(field_type, existing_default)
-            sqlmodel_fi = _inherit_resolved_field(
-                sqlmodel_fi, resolved, FieldInfo.from_annotation(rebuilt).metadata,
-            )
-        elif existing_default is Undefined:
-            base_fi = next(
-                (
-                    base_fields[field_name]
-                    for base in bases
-                    if (base_fields := getattr(base, 'model_fields', None)) and field_name in base_fields
-                ),
-                None,
-            )
-            if base_fi is not None and field_name not in own_names:
-                # An inherited field (the class body does not declare it). Its
-                # right-hand ``= Field(...)`` lives in the base class, not in
-                # ``attrs``; without this branch the injected
-                # ``attrs[field_name]`` replaces the inherited field with the
-                # alias's ``Field`` alone, and a column declared
-                # ``Field(index=True)`` in a base class loses its index.
-                sqlmodel_fi = _inherit_resolved_field(
-                    sqlmodel_fi, base_fi, FieldInfo.from_annotation(rebuilt).metadata,
-                )
-            elif (
+        elif base_fi is not None and field_name not in own_names:
+            # An inherited field (the class body does not declare it). Its
+            # right-hand side lives in the base class, not in ``attrs``: the
+            # base's resolved field is the declaration's resolution. Without it
+            # a column declared ``Field(index=True)`` in a base class loses its
+            # index.
+            resolved = base_fi
+        else:
+            resolved = FieldInfo.from_annotation(field_type)
+            if (
                     base_fi is not None
-                    and sqlmodel_fi.default is Undefined
-                    and sqlmodel_fi.default_factory is None
+                    and resolved.default is Undefined
+                    and resolved.default_factory is None
             ):
                 # Re-declared in the class body without a right-hand side:
-                # only the default is inherited.
+                # the base's default is inherited.
                 if base_fi.default is not Undefined:
-                    sqlmodel_fi.default = base_fi.default
+                    resolved.default = base_fi.default
                 elif base_fi.default_factory is not None:
-                    sqlmodel_fi.default_factory = base_fi.default_factory
+                    resolved.default_factory = base_fi.default_factory
+        sqlmodel_fi = _inherit_resolved_field(
+            sqlmodel_fis, resolved, FieldInfo.from_annotation(rebuilt).metadata,
+        )
 
         # Inject SQLModel FieldInfo as field default (equivalent to = Field(...) style)
         attrs[field_name] = sqlmodel_fi