plain.postgres 0.109.0__tar.gz → 0.110.0__tar.gz

{plain_postgres-0.109.0 → plain_postgres-0.110.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.109.0
+Version: 0.110.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause

{plain_postgres-0.109.0 → plain_postgres-0.110.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,16 @@
 # plain-postgres changelog
 
+## [0.110.0](https://github.com/dropseed/plain/releases/plain-postgres@0.110.0) (2026-06-17)
+
+### What's changed
+
+- Internal: the foreign-key/related-field internals are collapsed to the single-column-to-`id` model Plain actually uses, removing the inherited Django composite-key and `to_field` scaffolding. `PathInfo.target_fields` (a tuple) becomes a scalar `target_field`, and a `Join` now holds one `join_col` pair instead of a `join_cols` list. The unused multi-column helpers go with it: `RelatedField.resolve_related_fields()`, the `related_fields`/`local_related_fields`/`foreign_related_fields` properties, `ForeignKeyField.get_reverse_joining_columns()`, and `ForeignObjectRel.get_related_field()` / `field_name` / `set_field_name()` / `db_type` / the `multiple` flag (along with its now-dead reverse-cache priming, left over from the long-removed one-to-one relation). `get_local_related_value()`, `get_foreign_related_value()`, and the join-column accessors now return scalars instead of 1-tuples. ([cbd15fb707](https://github.com/dropseed/plain/commit/cbd15fb707))
+- Internal: the related-lookup prep path (`related_lookups.py`, `lookups.py`) now narrows on `RelatedField | ForeignObjectRel` to find a relation's target field instead of duck-typing with `getattr(output_field, "target_field")` / `hasattr(..., "path_infos")`, so the dependency is greppable, type-checked, and fails loudly if it's ever removed rather than silently falling back. ([cbd15fb707](https://github.com/dropseed/plain/commit/cbd15fb707))
+
+### Upgrade instructions
+
+- No changes required. These are internal ORM query-construction details — how foreign keys, reverse relations, and many-to-many relations behave (filtering, prefetching, related-manager access) is unchanged.
+
 ## [0.109.0](https://github.com/dropseed/plain/releases/plain-postgres@0.109.0) (2026-06-17)
 
 ### What's changed
@@ -14,7 +25,7 @@
 - Remove any `db_constraint=False` arguments from `ForeignKeyField`. Foreign keys are always DB-constrained now; an unconstrained FK (e.g. for soft/cross-system references) is no longer supported.
 - Remove `limit_choices_to=` from `ForeignKeyField` / `ManyToManyField` definitions. To constrain the rows offered for a relation, filter the related queryset explicitly in your form or view.
 - Replace any `QuerySet.complex_filter(...)` calls with `.filter(...)` — pass a dict of lookups or a `Q` object directly.
-- Most projects use none of these and need no changes. The `/plain-upgrade` skill handles the rewrites.
+- Most projects use none of these and need no changes.
 
 ## [0.108.1](https://github.com/dropseed/plain/releases/plain-postgres@0.108.1) (2026-06-09)
 
@@ -57,7 +68,7 @@
 
 ### Upgrade instructions
 
-- Replace `form.save()` with `form.create()` in create flows and `form.update()` in update flows. The `/plain-upgrade` skill rewrites these for you — the create-vs-update choice is context-dependent, so it reasons per call site.
+- Replace `form.save()` with `form.create()` in create flows and `form.update()` in update flows.
 - `form.update(fields=[...])` is available to limit the columns written (a pass-through to `Model.update(fields=...)`).
 - For the old `form.save(commit=False)` pattern (set extra non-form attributes, then save), assign those attributes on `form.instance` after `is_valid()`, then call `form.create()` / `form.update()` — m2m data is still saved for you, so the separate `save_m2m()` step is no longer needed:
 
@@ -79,7 +90,7 @@
 
 ### Upgrade instructions
 
-- Replace `obj.save()` with `obj.create()` for a new row or `obj.update()` for an existing one; `obj.save(update_fields=[...])` becomes `obj.update(fields=[...])`. The `/plain-upgrade` skill rewrites these for you — the create-vs-update choice is context-dependent, so it reasons per call site.
+- Replace `obj.save()` with `obj.create()` for a new row or `obj.update()` for an existing one; `obj.save(update_fields=[...])` becomes `obj.update(fields=[...])`.
 - Remove `force_insert=`/`force_update=` — `create()` and `update()` are the explicit forms.
 - Don't pass `id=` to a model constructor; load existing rows with `Model.query.get(id=...)`.
 - Catch `ValidationError` (or `(psycopg.IntegrityError, ValidationError)` when retrying) for unique/check conflicts on instance writes. Inside an open `transaction.atomic()` a violation aborts the transaction — wrap the write in its own `atomic()` to catch and continue.

{plain_postgres-0.109.0 → plain_postgres-0.110.0}/plain/postgres/base.py

@@ -538,9 +538,6 @@ class Model(metaclass=ModelBase):
                 # constraints aren't supported by the database, there's the
                 # unavoidable risk of data corruption.
                 if obj.id is None:
-                    # Remove the object from a related instance cache.
-                    if not field.remote_field.multiple:
-                        field.remote_field.delete_cached_value(obj)
                     raise ValueError(
                         f"{operation_name}() prohibited to prevent data loss due to unsaved "
                         f"related object '{field.name}'."
@@ -549,10 +546,10 @@ class Model(metaclass=ModelBase):
                     # Set related object if it has been saved after an
                     # assignment.
                     setattr(self, field.name, obj)
-                # If the relationship's pk/to_field was changed, clear the
-                # cached relationship. Compare the cached object's key against
-                # the raw key value -- not getattr(self, field.name), which
-                # for a foreign key returns the related object, not the key.
+                # If the relationship's key was changed, clear the cached
+                # relationship. Compare the cached object's key against the raw
+                # key value -- not getattr(self, field.name), which for a
+                # foreign key returns the related object, not the key.
                 if getattr(obj, field.target_field.name) != field.value_from_object(
                     self
                 ):
@@ -622,7 +619,7 @@ class Model(metaclass=ModelBase):
             raise ValueError(
                 f"Unsaved model instance {self!r} cannot be used in an ORM query."
             )
-        return getattr(self, field.remote_field.get_related_field().name)
+        return getattr(self, field.target_field.name)
 
     def clean(self) -> None:
         """

{plain_postgres-0.109.0 → plain_postgres-0.110.0}/plain/postgres/fields/related.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING, Any, Self, cast
 
 from plain.postgres.constants import LOOKUP_SEP
 from plain.postgres.deletion import SET_NULL, OnDelete
-from plain.postgres.exceptions import FieldDoesNotExist, FieldError
+from plain.postgres.exceptions import FieldDoesNotExist
 from plain.postgres.query_utils import PathInfo
 from plain.postgres.utils import make_model_tuple
 from plain.preflight import PreflightResult
@@ -277,7 +277,6 @@ class RelatedField(FieldCacheMixin, Field):
         self.name = self.name or (
             self.remote_field.model.model_options.model_name + "_" + "id"
         )
-        self.remote_field.set_field_name()
 
     def do_related_class(self, other: type[Model], cls: type[Model]) -> None:
         self.set_attributes_from_rel()
@@ -294,16 +293,12 @@ class RelatedField(FieldCacheMixin, Field):
     @property
     def target_field(self) -> Field:
         """
-        When filtering against this relation, return the field on the remote
-        model against which the filtering should happen.
+        The remote field this relation filters against. Read dynamically by the
+        related-lookup prep path (`output_field.target_field`). ForeignKeyField
+        overrides this with a direct, cached lookup; ManyToManyField uses this
+        path-based form.
         """
-        target_fields = self.path_infos[-1].target_fields
-        if len(target_fields) > 1:
-            raise FieldError(
-                "The relation has multiple target fields, but only single target field "
-                "was asked for"
-            )
-        return target_fields[0]
+        return self.path_infos[-1].target_field
 
     def get_cache_name(self) -> str:
         assert self.name is not None, "Field name must be set"
@@ -372,49 +367,28 @@ class ForeignKeyField(ColumnField, RelatedField):
 
     def __copy__(self) -> ForeignKeyField:
         obj = super().__copy__()
-        # Remove any cached PathInfo values.
+        # Remove cached values that depend on the (possibly not-yet-resolved)
+        # remote model.
+        obj.__dict__.pop("target_field", None)
         obj.__dict__.pop("path_infos", None)
         obj.__dict__.pop("reverse_path_infos", None)
         return obj
 
-    @cached_property
-    def related_fields(self) -> list[tuple[ForeignKeyField, Field]]:
-        return self.resolve_related_fields()
+    def get_local_related_value(self, instance: Model) -> Any:
+        # The local field is the foreign key itself; read its raw key value, not
+        # the related object the descriptor returns.
+        return self._get_raw_value(instance)
 
-    @cached_property
-    def local_related_fields(self) -> tuple[Field, ...]:
-        return tuple(lhs_field for lhs_field, rhs_field in self.related_fields)
+    def get_foreign_related_value(self, instance: Model) -> Any:
+        # A foreign key always points at the remote instance's id.
+        return instance.id
 
-    @cached_property
-    def foreign_related_fields(self) -> tuple[Field, ...]:
-        return tuple(
-            rhs_field for lhs_field, rhs_field in self.related_fields if rhs_field
-        )
-
-    def get_local_related_value(self, instance: Model) -> tuple[Any, ...]:
-        # The single local field is the foreign key itself.
-        if self.primary_key:
-            return (instance.id,)
-        # Read the raw key value, not the related object the descriptor returns.
-        return (self._get_raw_value(instance),)
-
-    def get_foreign_related_value(self, instance: Model) -> tuple[Any, ...]:
-        # Always returns the id of the foreign instance
-        return (instance.id,)
-
-    def get_joining_columns(
-        self, reverse_join: bool = False
-    ) -> tuple[tuple[str, str], ...]:
-        # Always returns a single column pair
+    def get_joining_columns(self, reverse_join: bool = False) -> tuple[str, str]:
+        # A foreign key joins one column pair: this field's column and the
+        # target's id column.
         if reverse_join:
-            from_field, to_field = self.related_fields[0]
-            return ((to_field.column, from_field.column),)
-        else:
-            from_field, to_field = self.related_fields[0]
-            return ((from_field.column, to_field.column),)
-
-    def get_reverse_joining_columns(self) -> tuple[tuple[str, str], ...]:
-        return self.get_joining_columns(reverse_join=True)
+            return (self.target_field.column, self.column)
+        return (self.column, self.target_field.column)
 
     def get_path_info(self, filtered_relation: Any = None) -> list[PathInfo]:
         """Get path from this field to the related model."""
@@ -424,7 +398,7 @@ class ForeignKeyField(ColumnField, RelatedField):
             PathInfo(
                 from_meta=from_meta,
                 to_meta=meta,
-                target_fields=self.foreign_related_fields,
+                target_field=self.target_field,
                 join_field=self,
                 m2m=False,
                 direct=True,
@@ -444,9 +418,10 @@ class ForeignKeyField(ColumnField, RelatedField):
             PathInfo(
                 from_meta=from_meta,
                 to_meta=meta,
-                target_fields=(meta.get_forward_field("id"),),
+                target_field=meta.get_forward_field("id"),
                 join_field=self.remote_field,
-                m2m=not self.primary_key,
+                # The reverse of a foreign key always fans out to many rows.
+                m2m=True,
                 direct=False,
                 filtered_relation=filtered_relation,
             )
@@ -500,26 +475,14 @@ class ForeignKeyField(ColumnField, RelatedField):
     def to_python(self, value: Any) -> Any:
         return self.target_field.to_python(value)
 
-    @property
+    @cached_property
     def target_field(self) -> Field:
-        return self.foreign_related_fields[0]
-
-    def resolve_related_fields(self) -> list[tuple[ForeignKeyField, Field]]:
+        """A foreign key points at exactly one column: the remote model's id."""
         if isinstance(self.remote_field.model, str):
             raise ValueError(
                 f"Related model {self.remote_field.model!r} cannot be resolved"
             )
-        from_field = self
-        to_field = self.remote_field.model._model_meta.get_forward_field("id")
-        related_fields: list[tuple[ForeignKeyField, Field]] = [(from_field, to_field)]
-
-        for from_field, to_field in related_fields:
-            if to_field and to_field.model != self.remote_field.model:
-                raise FieldError(
-                    f"'{self.model.model_options.label}.{self.name}' refers to field '{to_field.name}' which is not local to model "
-                    f"'{self.remote_field.model.model_options.label}'."
-                )
-        return related_fields
+        return self.remote_field.model._model_meta.get_forward_field("id")
 
     def set_attributes_from_name(self, name: str) -> None:
         super().set_attributes_from_name(name)
@@ -574,11 +537,8 @@ class ForeignKeyField(ColumnField, RelatedField):
 
     def get_col(self, alias: str | None, output_field: Field | None = None) -> Any:
         if output_field is None:
+            # A foreign key resolves to its target's id column.
             output_field = self.target_field
-            while isinstance(output_field, ForeignKeyField):
-                output_field = output_field.target_field
-                if output_field is self:
-                    raise ValueError("Cannot resolve output_field.")
         return super().get_col(alias, output_field)
 
 
@@ -1048,13 +1008,6 @@ class ManyToManyField(RelatedField):
             self._get_m2m_reverse_attr, related, "name"
         )
 
-        get_m2m_rel = partial(self._get_m2m_attr, related, "remote_field")
-        self.m2m_target_field_name = lambda: get_m2m_rel().field_name
-        get_m2m_reverse_rel = partial(
-            self._get_m2m_reverse_attr, related, "remote_field"
-        )
-        self.m2m_reverse_target_field_name = lambda: get_m2m_reverse_rel().field_name
-
     def set_attributes_from_rel(self) -> None:
         pass
 

{plain_postgres-0.109.0 → plain_postgres-0.110.0}/plain/postgres/fields/related_descriptors.py

@@ -23,11 +23,6 @@ reverse foreign key relation.
 1. Related instance on the forward side of a foreign key relation:
    ``ForwardForeignKeyDescriptor``.
 
-   Uniqueness of foreign key values is irrelevant to accessing the related
-   instance, making the many-to-one and one-to-one cases identical as far as
-   the descriptor is concerned. The constraint is checked upstream (unicity
-   validation in forms) or downstream (unique indexes in the database).
-
 2. Related objects manager for related instances on the forward or reverse
    sides of a many-to-many relation: ``ForwardManyToManyDescriptor``.
 
@@ -94,22 +89,14 @@ class ForwardForeignKeyDescriptor:
 
         rel_obj_attr = self.field.get_foreign_related_value
         instance_attr = self.field.get_local_related_value
-        instances_dict = {instance_attr(inst): inst for inst in instances}
-        related_field = self.field.foreign_related_fields[0]
-        remote_field = self.field.remote_field
+        related_field = self.field.target_field
 
         # A foreign key is single-column, so prefetch with a join-less IN query.
         query = {
-            f"{related_field.name}__in": {instance_attr(inst)[0] for inst in instances}
+            f"{related_field.name}__in": {instance_attr(inst) for inst in instances}
         }
         queryset = queryset.filter(**query)
 
-        # Since we're going to assign directly in the cache,
-        # we must manage the reverse relation cache manually.
-        if not remote_field.multiple:
-            for rel_obj in queryset:
-                instance = instances_dict[rel_obj_attr(rel_obj)]
-                remote_field.set_cached_value(rel_obj, instance)
         return (
             queryset,
             rel_obj_attr,
@@ -152,9 +139,6 @@ class ForwardForeignKeyDescriptor:
                 # no query. Accessing any other field triggers the full-row
                 # deferred load.
                 rel_obj = remote_model.from_db([target_name], [pk_value])
-                # For a one-to-one relation, prime the reverse cache too.
-                if not self.field.remote_field.multiple:
-                    self.field.remote_field.set_cached_value(rel_obj, instance)
             self.field.set_cached_value(instance, rel_obj)
 
         # Checked on every access, including a cached None: a non-nullable
@@ -186,11 +170,6 @@ class ForwardForeignKeyDescriptor:
         remote_field = self.field.remote_field
 
         if value is None:
-            # Clear the reverse cache on any previously-related object so a
-            # later delete of it does not cascade into this instance.
-            related = self.field.get_cached_value(instance, default=None)
-            if related is not None and not remote_field.multiple:
-                remote_field.set_cached_value(related, None)
             instance.__dict__[name] = None
             self.field.set_cached_value(instance, None)
             return
@@ -199,9 +178,6 @@ class ForwardForeignKeyDescriptor:
             # A related model instance: store its key, cache the object.
             instance.__dict__[name] = getattr(value, self.field.target_field.name)
             self.field.set_cached_value(instance, value)
-            # For a one-to-one relation, prime the reverse cache.
-            if not remote_field.multiple:
-                remote_field.set_cached_value(value, instance)
             return
 
         if isinstance(value, Model | bool):
@@ -217,12 +193,8 @@ class ForwardForeignKeyDescriptor:
         # A bare related key value (e.g. child.parent = 5).
         new_value = self.field.to_python(value)
         if instance.__dict__.get(name) != new_value:
-            # The key actually changed -- clear the reverse cache on any
-            # previously-related object and drop the now-stale forward cache.
+            # The key actually changed -- drop the now-stale forward cache.
             # Re-storing the same key (e.g. by clean_fields) keeps the cache.
-            related = self.field.get_cached_value(instance, default=None)
-            if related is not None and not remote_field.multiple:
-                remote_field.set_cached_value(related, None)
             if self.field.is_cached(instance):
                 self.field.delete_cached_value(instance)
         instance.__dict__[name] = new_value

{plain_postgres-0.109.0 → plain_postgres-0.110.0}/plain/postgres/fields/related_lookups.py

@@ -18,36 +18,43 @@ if TYPE_CHECKING:
     from plain.postgres.sql.compiler import SQLCompiler
 
 
-def get_normalized_value(value: Any, lhs: Any) -> tuple[Any, ...]:
-    from plain.postgres import Model
+def _related_target_field(lhs: Any) -> Any:
+    """The remote field a relational lhs filters against (e.g. the target's id),
+    or None when the lhs is not a relation.
+
+    Narrowing on the relation types keeps this explicit and type-checked rather
+    than probing for a ``path_infos`` attribute with hasattr().
+    """
     from plain.postgres.fields.related import RelatedField
+    from plain.postgres.fields.reverse_related import ForeignObjectRel
+
+    output_field = lhs.output_field
+    if isinstance(output_field, RelatedField | ForeignObjectRel):
+        return output_field.path_infos[-1].target_field
+    return None
+
+
+def get_normalized_value(value: Any, lhs: Any) -> Any:
+    from plain.postgres import Model
 
     if isinstance(value, Model):
         if value.id is None:
             raise ValueError("Model instances passed to related filters must be saved.")
-        # FK relations are always single-column (target is remote `id`), so
-        # path_infos[-1].target_fields is a 1-tuple.
-        source = lhs.output_field.path_infos[-1].target_fields[0]
-        while not isinstance(value, source.model) and isinstance(source, RelatedField):
-            source = source.remote_field.model._model_meta.get_field(
-                source.remote_field.field_name
-            )
-        return (getattr(value, source.name),)
-    if not isinstance(value, tuple):
-        return (value,)
+        # FK relations are always single-column, targeting the remote `id`.
+        source = lhs.output_field.path_infos[-1].target_field
+        return getattr(value, source.name)
     return value
 
 
 class RelatedIn(In):
     def get_prep_lookup(self) -> list[Any]:
         if self.rhs_is_direct_value():
-            self.rhs = [get_normalized_value(val, self.lhs)[0] for val in self.rhs]
+            self.rhs = [get_normalized_value(val, self.lhs) for val in self.rhs]
             # We need to run the related field's get_prep_value(). Consider
             # case ForeignKeyField to IntegerField given value 'abc'. The
             # ForeignKeyField itself doesn't have validation for non-integers,
             # so we must run validation using the target field.
-            if hasattr(self.lhs.output_field, "path_infos"):
-                target_field = self.lhs.output_field.path_infos[-1].target_fields[-1]
+            if target_field := _related_target_field(self.lhs):
                 self.rhs = [target_field.get_prep_value(v) for v in self.rhs]
         return super().get_prep_lookup()
 
@@ -61,13 +68,12 @@ class RelatedLookupMixin(Lookup):
 
     def get_prep_lookup(self) -> Any:
         if not hasattr(self.rhs, "resolve_expression"):
-            self.rhs = get_normalized_value(self.rhs, self.lhs)[0]
+            self.rhs = get_normalized_value(self.rhs, self.lhs)
             # We need to run the related field's get_prep_value(). Consider case
             # ForeignKeyField to IntegerField given value 'abc'. The ForeignKeyField itself
             # doesn't have validation for non-integers, so we must run validation
             # using the target field.
-            if self.prepare_rhs and hasattr(self.lhs.output_field, "path_infos"):
-                target_field = self.lhs.output_field.path_infos[-1].target_fields[-1]
+            if self.prepare_rhs and (target_field := _related_target_field(self.lhs)):
                 self.rhs = target_field.get_prep_value(self.rhs)
 
         return super().get_prep_lookup()

{plain_postgres-0.109.0 → plain_postgres-0.110.0}/plain/postgres/fields/related_managers.py

@@ -97,12 +97,12 @@ class ReverseForeignKeyManager(BaseRelatedManager[T, QS]):
         self.allow_null = self.field.allow_null
 
     def _check_fk_val(self) -> None:
-        for field in self.field.foreign_related_fields:
-            if getattr(self.instance, field.name) is None:
-                raise ValueError(
-                    f'"{self.instance!r}" needs to have a value for field '
-                    f'"{field.name}" before this relationship can be used.'
-                )
+        field = self.field.target_field
+        if getattr(self.instance, field.name) is None:
+            raise ValueError(
+                f'"{self.instance!r}" needs to have a value for field '
+                f'"{field.name}" before this relationship can be used.'
+            )
 
     def _apply_rel_filters(self, queryset: QuerySet) -> QuerySet:
         """
@@ -110,13 +110,10 @@ class ReverseForeignKeyManager(BaseRelatedManager[T, QS]):
         """
         queryset._defer_next_filter = True
         queryset = queryset.filter(**self.core_filters)
-        for field in self.field.foreign_related_fields:
-            val = getattr(self.instance, field.name)
-            if val is None:
-                return queryset.none()
-
         target_field = self.field.target_field
         rel_obj_id = getattr(self.instance, target_field.name)
+        if rel_obj_id is None:
+            return queryset.none()
         queryset._known_related_objects = {self.field: {rel_obj_id: self.instance}}
         return queryset
 
@@ -129,9 +126,8 @@ class ReverseForeignKeyManager(BaseRelatedManager[T, QS]):
             pass  # nothing to clear from cache
 
     def get_queryset(self) -> QS:
-        # Even if this relation is not to primary key, we require still primary key value.
-        # The wish is that the instance has been already saved to DB,
-        # although having a primary key value isn't a guarantee of that.
+        # The instance must have a primary key value to be related against,
+        # though that isn't a guarantee it has actually been saved to the DB.
         if self.instance.id is None:
             raise ValueError(
                 f"{self.instance.__class__.__name__!r} instance needs to have a "
@@ -312,8 +308,7 @@ class ManyToManyManager(BaseRelatedManager[T, QS]):
     target_field_name: str
     symmetrical: bool
     core_filters: dict[str, Any]
-    id_field_names: dict[str, str]
-    related_val: tuple[Any, ...]
+    related_val: Any
 
     def __init__(
         self,
@@ -357,22 +352,20 @@ class ManyToManyManager(BaseRelatedManager[T, QS]):
             self.through._model_meta.get_forward_field(self.target_field_name),
         )
 
-        self.core_filters = {}
-        self.id_field_names = {}
-        for lh_field, rh_field in self.source_field.related_fields:
-            rh_name = rh_field.name
-            assert rh_name is not None
-            core_filter_key = f"{self.query_field_name}__{rh_name}"
-            self.core_filters[core_filter_key] = getattr(instance, rh_name)
-            self.id_field_names[lh_field.name] = rh_field.name  # ty: ignore[invalid-assignment]
-
-        self.related_val = self.source_field.get_foreign_related_value(instance)
-        if None in self.related_val:
+        source_fk = self.source_field
+        rh_name = source_fk.target_field.name
+        assert rh_name is not None
+        self.core_filters = {
+            f"{self.query_field_name}__{rh_name}": getattr(instance, rh_name)
+        }
+
+        self.related_val = source_fk.get_foreign_related_value(instance)
+        if self.related_val is None:
             raise ValueError(
-                f'"{instance!r}" needs to have a value for field "{self.id_field_names[self.source_field_name]}" before '
+                f'"{instance!r}" needs to have a value for field "{rh_name}" before '
                 "this many-to-many relationship can be used."
             )
-        # Even if this relation is not to primary key, we require still primary key value.
+        # The instance must have a primary key value to be related against.
         if instance.id is None:
             raise ValueError(
                 f"{instance.__class__.__name__!r} instance needs to have a primary key value before "
@@ -423,20 +416,16 @@ class ManyToManyManager(BaseRelatedManager[T, QS]):
         qn = quote_name
         queryset = queryset.extra(
             select={
-                f"_prefetch_related_val_{f.name}": f"{qn(join_table)}.{qn(f.column)}"
-                for f in fk.local_related_fields
+                f"_prefetch_related_val_{fk.name}": f"{qn(join_table)}.{qn(fk.column)}"
             }
         )
         conn = get_connection()
+        target_field = fk.target_field
         return (
             queryset,
-            lambda result: tuple(
-                getattr(result, f"_prefetch_related_val_{f.name}")
-                for f in fk.local_related_fields
-            ),
-            lambda inst: tuple(
-                f.get_db_prep_value(f.value_from_object(inst), conn)
-                for f in fk.foreign_related_fields
+            lambda result: getattr(result, f"_prefetch_related_val_{fk.name}"),
+            lambda inst: target_field.get_db_prep_value(
+                target_field.value_from_object(inst), conn
             ),
             False,
             self.prefetch_cache_name,
@@ -472,7 +461,7 @@ class ManyToManyManager(BaseRelatedManager[T, QS]):
                 new_objs = []
                 for obj in objs:
                     fk_val = (
-                        self.target_field.get_foreign_related_value(obj)[0]
+                        self.target_field.get_foreign_related_value(obj)
                         if isinstance(obj, self.model)
                         else self.target_field.get_prep_value(obj)
                     )
@@ -525,7 +514,7 @@ class ManyToManyManager(BaseRelatedManager[T, QS]):
         )  # M2M through model fields are always ForeignKey
         for obj in objs:
             if isinstance(obj, self.model):
-                target_id = target_field.get_foreign_related_value(obj)[0]
+                target_id = target_field.get_foreign_related_value(obj)
                 if target_id is None:
                     raise ValueError(
                         f'Cannot add "{obj!r}": the value for field "{target_field_name}" is None'
@@ -548,7 +537,7 @@ class ManyToManyManager(BaseRelatedManager[T, QS]):
         """Return the subset of ids of `objs` that aren't already assigned to this relationship."""
         vals = self.through.query.values_list(target_field_name, flat=True).filter(
             **{
-                source_field_name: self.related_val[0],
+                source_field_name: self.related_val,
                 f"{target_field_name}__in": target_ids,
             }
         )
@@ -577,7 +566,7 @@ class ManyToManyManager(BaseRelatedManager[T, QS]):
                     self.through(
                         **through_defaults,
                         **{
-                            source_field_name: self.related_val[0],
+                            source_field_name: self.related_val,
                             target_field_name: target_id,
                         },
                     )
@@ -595,7 +584,7 @@ class ManyToManyManager(BaseRelatedManager[T, QS]):
         old_ids = set()
         for obj in objs:
             if isinstance(obj, self.model):
-                fk_val = self.target_field.get_foreign_related_value(obj)[0]
+                fk_val = self.target_field.get_foreign_related_value(obj)
                 old_ids.add(fk_val)
             else:
                 old_ids.add(obj)