plain.postgres 0.103.5__tar.gz → 0.104.0__tar.gz

plain_postgres-0.103.5/plain/postgres/README.md → plain_postgres-0.104.0/PKG-INFO

@@ -1,3 +1,16 @@
+Metadata-Version: 2.4
+Name: plain.postgres
+Version: 0.104.0
+Summary: Model your data and store it in a database.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: plain<1.0.0,>=0.134.0
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: psycopg>=3.2
+Description-Content-Type: text/markdown
+
 # plain.postgres
 
 **Model your data and store it in a database.**
@@ -410,6 +423,8 @@ posts = Post.query.all()
 posts = Post.query.defer("body").all()
 ```
 
+Reading any deferred field on an instance loads every still-missing column in a single query, not just the field you asked for. Defer columns you don't intend to access on that instance, and prefer `.values()` / `.values_list()` when you want one column without ever materializing the rest. The foreign key column is the exception: accessing a deferred foreign key loads only the foreign key column, so the partial-related-instance shortcut stays cheap.
+
 #### Use `.iterator()` for large result sets
 
 Process rows in chunks instead of loading everything into memory.
@@ -929,6 +944,21 @@ class Book(postgres.Model):
     tags = types.ManyToManyField("Tag")
 ```
 
+### Foreign key access
+
+Accessing a foreign key gives you the related object without a query — only its primary key is loaded up front:
+
+```python
+book = Book.query.get(id=1)
+book.author        # no query — a partial Author instance
+book.author.id     # no query — the foreign key value
+book.author.name   # one query — loads the rest of the row
+```
+
+The first access to any non-key field loads the whole row in a single query. There is no separate `author_id` attribute — `book.author.id` is the foreign key value, and it is type-checked because `book.author` is an `Author`. In loops, use `select_related()` to load related rows up front and avoid a query per row.
+
+The partial-instance shortcut relies on the database guaranteeing the row exists. A foreign key declared with `db_constraint=False` has no such guarantee, so it is queried on access instead — a stale key raises `DoesNotExist` right away rather than yielding a placeholder.
+
 ### Reverse relationships
 
 When you define a `ForeignKey` or `ManyToManyField`, Plain automatically creates a reverse accessor on the related model (like `author.book_set`). You can explicitly declare these reverse relationships using [`ReverseForeignKey`](./fields/reverse_descriptors.py#ReverseForeignKey) and [`ReverseManyToMany`](./fields/reverse_descriptors.py#ReverseManyToMany):

{plain_postgres-0.103.5 → plain_postgres-0.104.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,25 @@
 # plain-postgres changelog
 
+## [0.104.0](https://github.com/dropseed/plain/releases/plain-postgres@0.104.0) (2026-05-22)
+
+### What's changed
+
+- **Foreign keys now return a partial related instance instead of an `_id` attribute.** Reading `book.author` is query-free — it returns an `Author` instance with only its primary key loaded. `book.author.id` gives the foreign key value, and accessing any other field (`book.author.name`) triggers a single deferred-load query for the whole row. The descriptor caches the resolved object so subsequent accesses do not re-query. `select_related()` continues to populate the cache up front for loops. ([b3be028b7b](https://github.com/dropseed/plain/commit/b3be028b7b))
+- **The `<fk>_id` shadow attribute is gone.** There is no `book.author_id` anymore — the raw foreign key column lives in `instance.__dict__` under the field name (`book.__dict__["author"]`) and is reached through the descriptor. `book.author.id` is the replacement read path and is type-checked because `book.author` is an `Author`. Writes that previously assigned `book.author_id = 5` now need to assign the key (or a related instance) through `book.author = 5` — the descriptor accepts a bare primary key value, a model instance, or `None`. ([3baa1c0404](https://github.com/dropseed/plain/commit/3baa1c0404), [b3be028b7b](https://github.com/dropseed/plain/commit/b3be028b7b))
+- **`Field.attname` and `Field.get_attname()` are removed.** Every internal use was the same as `Field.name`; the dual-keying only existed to track the `_id` suffix on foreign keys, which now lives on `Field.column` instead. Use `field.name` for the attribute (and instance-dict key) and `field.column` for the database column. ([6a462a874c](https://github.com/dropseed/plain/commit/6a462a874c), [e556bb7d63](https://github.com/dropseed/plain/commit/e556bb7d63))
+- **Foreign keys with `db_constraint=False` are queried on access** rather than returning a partial instance. Without a database FK constraint a stale key cannot be assumed valid, so the descriptor issues a `SELECT` and raises `RelatedObjectDoesNotExist` immediately if the row is missing — the same exception an empty foreign key raises. Constrained foreign keys (the default) keep the no-query partial-instance shortcut. ([d341d902b4](https://github.com/dropseed/plain/commit/d341d902b4))
+- **Reading a deferred field now hydrates every still-missing concrete column in one query**, not just the field you accessed. This is what makes the partial foreign-key instance cheap to use beyond its primary key — first non-key access loads the whole row. The foreign key column itself is the exception and is loaded on its own when deferred via `.only()` / `.defer()`, so the partial-instance shortcut stays cheap. ([2440e415cb](https://github.com/dropseed/plain/commit/2440e415cb))
+- The descriptor's deferred foreign-key load now goes through `_get_raw_value()`, so a `.only()` queryset that excludes the FK column still resolves the related object on access without mistaking the deferred column for `NULL`. ([d9765979ba](https://github.com/dropseed/plain/commit/d9765979ba))
+- `Field.__delete__` reordered so a missing entry raises `AttributeError` without first wiping the related-object cache — repeated `del`s no longer silently evict cached descriptors. ([b8949f00d0](https://github.com/dropseed/plain/commit/b8949f00d0))
+- Internal cleanup: removed the unused `ForeignKeyField.reverse_related_fields` property, the dead composite-key branches in foreign-key resolution, and the unreachable code left over from the `attname` collapse. ([98b27c5f8a](https://github.com/dropseed/plain/commit/98b27c5f8a), [92e905f25e](https://github.com/dropseed/plain/commit/92e905f25e), [bfcac9a435](https://github.com/dropseed/plain/commit/bfcac9a435))
+
+### Upgrade instructions
+
+- **Audit every `<fk>_id` access** — these attributes no longer exist. Reads (`obj.author_id`) and especially writes (`obj.author_id = 5`) need to move to the field name: `obj.author.id` for reads, `obj.author = 5` for writes. **Pay particular attention to assignments under `# type: ignore` or other suppression** — a stray `obj.author_id = ...` write now creates a plain Python attribute on the instance and silently does nothing on save, because the ORM only persists the descriptor-backed value at `obj.author`. Grep for `_id =`, `_id=` (in `.create()` / `.update()` kwargs), and `_id` template/queryset references on your models. Querysets and lookups (`Author.query.filter(book__author_id=5)`) are unaffected — only attribute access on instances changed.
+- **Stop reading `Field.attname` / calling `Field.get_attname()`.** Any custom field or introspection code that referenced these attributes must switch to `field.name` (the Python attribute) or `field.column` (the database column).
+- **Foreign keys declared with `db_constraint=False` now issue a query on first access** (previously: no query, partial instance). If you relied on accessing a constraint-less FK without a query, the behavior is intentionally stricter — a stale key now fails fast with `RelatedObjectDoesNotExist` instead of yielding a phantom instance that broke only on field access. Use `select_related()` to load these up front in loops.
+- **`.only()` / `.defer()` field lists**: deferred non-FK columns no longer load one-at-a-time. If you `.defer("body")` and later read `instance.body`, the resulting query now refreshes every still-deferred column in the same instance — defer only the columns you do not intend to read.
+
 ## [0.103.5](https://github.com/dropseed/plain/releases/plain-postgres@0.103.5) (2026-05-19)
 
 ### What's changed

plain_postgres-0.103.5/PKG-INFO → plain_postgres-0.104.0/plain/postgres/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.4
-Name: plain.postgres
-Version: 0.103.5
-Summary: Model your data and store it in a database.
-Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
-License-Expression: BSD-3-Clause
-License-File: LICENSE
-Requires-Python: >=3.13
-Requires-Dist: plain<1.0.0,>=0.134.0
-Requires-Dist: psycopg-pool>=3.2
-Requires-Dist: psycopg>=3.2
-Description-Content-Type: text/markdown
-
 # plain.postgres
 
 **Model your data and store it in a database.**
@@ -423,6 +410,8 @@ posts = Post.query.all()
 posts = Post.query.defer("body").all()
 ```
 
+Reading any deferred field on an instance loads every still-missing column in a single query, not just the field you asked for. Defer columns you don't intend to access on that instance, and prefer `.values()` / `.values_list()` when you want one column without ever materializing the rest. The foreign key column is the exception: accessing a deferred foreign key loads only the foreign key column, so the partial-related-instance shortcut stays cheap.
+
 #### Use `.iterator()` for large result sets
 
 Process rows in chunks instead of loading everything into memory.
@@ -942,6 +931,21 @@ class Book(postgres.Model):
     tags = types.ManyToManyField("Tag")
 ```
 
+### Foreign key access
+
+Accessing a foreign key gives you the related object without a query — only its primary key is loaded up front:
+
+```python
+book = Book.query.get(id=1)
+book.author        # no query — a partial Author instance
+book.author.id     # no query — the foreign key value
+book.author.name   # one query — loads the rest of the row
+```
+
+The first access to any non-key field loads the whole row in a single query. There is no separate `author_id` attribute — `book.author.id` is the foreign key value, and it is type-checked because `book.author` is an `Author`. In loops, use `select_related()` to load related rows up front and avoid a query per row.
+
+The partial-instance shortcut relies on the database guaranteeing the row exists. A foreign key declared with `db_constraint=False` has no such guarantee, so it is queried on access instead — a stale key raises `DoesNotExist` right away rather than yielding a placeholder.
+
 ### Reverse relationships
 
 When you define a `ForeignKey` or `ManyToManyField`, Plain automatically creates a reverse accessor on the related model (like `author.book_set`). You can explicitly declare these reverse relationships using [`ReverseForeignKey`](./fields/reverse_descriptors.py#ReverseForeignKey) and [`ReverseManyToMany`](./fields/reverse_descriptors.py#ReverseManyToMany):

{plain_postgres-0.103.5 → plain_postgres-0.104.0}/plain/postgres/agents/.claude/rules/plain-postgres.md

@@ -49,6 +49,7 @@ Run `uv run plain docs postgres` for full workflow details.
 Use `Model.query` to build querysets (e.g., `User.query.filter(is_active=True)`).
 
 - Use `select_related()` for FK access in loops, `prefetch_related()` for reverse/M2N
+- A foreign key returns a partial related object: `obj.author` and `obj.author.id` are query-free; other fields load on first access. There is no `obj.author_id` — use `obj.author.id`
 - Use `.annotate(Count(...))` instead of calling `.count()` per row
 - Fetch all data in the view — templates should never trigger queries
 - Use `.exists()` not `.count() > 0`, `.count()` not `len(qs)`

{plain_postgres-0.103.5 → plain_postgres-0.104.0}/plain/postgres/base.py

@@ -113,24 +113,21 @@ class Model(metaclass=ModelBase):
 
             is_related_object = False
             # Virtual field
-            if field.attname not in kwargs and field.column is None:
+            if field.name not in kwargs and field.column is None:
                 continue
             if isinstance(field, RelatedField) and isinstance(
                 field.remote_field, ForeignObjectRel
             ):
                 try:
-                    # Assume object instance was passed in.
+                    # A foreign key is given by name -- either a related
+                    # instance or a bare primary key value.
                     rel_obj = kwargs.pop(field.name)
                     is_related_object = True
                 except KeyError:
-                    try:
-                        # Object instance wasn't passed in -- must be an ID.
-                        val = kwargs.pop(field.attname)
-                    except KeyError:
-                        val = field.get_default()
+                    val = field.get_default()
             else:
                 try:
-                    val = kwargs.pop(field.attname)
+                    val = kwargs.pop(field.name)
                 except KeyError:
                     # This is done with an exception rather than the
                     # default argument on pop because we don't want
@@ -145,15 +142,13 @@ class Model(metaclass=ModelBase):
                         val = field.get_default()
 
             if is_related_object:
-                # If we are passed a related instance, set it using the
-                # field.name instead of field.attname (e.g. "user" instead of
-                # "user_id") so that the object gets properly cached (and type
-                # checked) by the RelatedObjectDescriptor.
+                # Assign through the descriptor so a related instance is
+                # cached and a bare key value is stored correctly.
                 if rel_obj is not _DEFERRED:
                     _setattr(self, field.name, rel_obj)
             else:
                 if val is not _DEFERRED:
-                    _setattr(self, field.attname, val)
+                    _setattr(self, field.name, val)
 
         # Handle any remaining kwargs (properties or virtual fields)
         property_names = meta._property_names
@@ -185,12 +180,12 @@ class Model(metaclass=ModelBase):
         if len(values) != len(cls._model_meta.concrete_fields):
             values_iter = iter(values)
             values = [
-                next(values_iter) if f.attname in field_names else DEFERRED
+                next(values_iter) if f.name in field_names else DEFERRED
                 for f in cls._model_meta.concrete_fields
             ]
         # Build kwargs dict from field names and values
         field_dict = dict(
-            zip((f.attname for f in cls._model_meta.concrete_fields), values)
+            zip((f.name for f in cls._model_meta.concrete_fields), values)
         )
         new = cls(**field_dict)
         new._state.adding = False
@@ -269,9 +264,9 @@ class Model(metaclass=ModelBase):
         Return a set containing names of deferred fields for this instance.
         """
         return {
-            f.attname
+            f.name
             for f in self._model_meta.concrete_fields
-            if f.attname not in self.__dict__
+            if f.name not in self.__dict__
         }
 
     def refresh_from_db(self, fields: list[str] | None = None) -> None:
@@ -309,19 +304,19 @@ class Model(metaclass=ModelBase):
             db_instance_qs = db_instance_qs.only(*fields)
         elif deferred_fields:
             fields = [
-                f.attname
+                f.name
                 for f in self._model_meta.concrete_fields
-                if f.attname not in deferred_fields
+                if f.name not in deferred_fields
             ]
             db_instance_qs = db_instance_qs.only(*fields)
 
         db_instance = db_instance_qs.get()
         non_loaded_fields = db_instance.get_deferred_fields()
         for field in self._model_meta.concrete_fields:
-            if field.attname in non_loaded_fields:
+            if field.name in non_loaded_fields:
                 # This field wasn't refreshed - skip ahead.
                 continue
-            setattr(self, field.attname, getattr(db_instance, field.attname))
+            setattr(self, field.name, field.value_from_object(db_instance))
             # Clear cached foreign keys.
             if isinstance(field, RelatedField) and field.is_cached(self):
                 field.delete_cached_value(self)
@@ -346,7 +341,7 @@ class Model(metaclass=ModelBase):
             field = self._model_meta.get_forward_field(field_name)
         except FieldDoesNotExist:
             return getattr(self, field_name)
-        return getattr(self, field.attname)
+        return field.value_from_object(self)
 
     def save(
         self,
@@ -393,7 +388,7 @@ class Model(metaclass=ModelBase):
             field_names = set()
             for field in self._model_meta.concrete_fields:
                 if not field.primary_key and not hasattr(field, "through"):
-                    field_names.add(field.attname)
+                    field_names.add(field.name)
             loaded_fields = field_names.difference(deferred_fields)
             if loaded_fields:
                 update_fields = frozenset(loaded_fields)
@@ -454,11 +449,7 @@ class Model(metaclass=ModelBase):
         non_pks = [f for f in meta.local_concrete_fields if not f.primary_key]
 
         if update_fields:
-            non_pks = [
-                f
-                for f in non_pks
-                if f.name in update_fields or f.attname in update_fields
-            ]
+            non_pks = [f for f in non_pks if f.name in update_fields]
 
         id_field = meta.get_forward_field("id")
         id_val = self.id
@@ -469,7 +460,7 @@ class Model(metaclass=ModelBase):
             # stays None and the INSERT emits DEFAULT.
             if isinstance(id_field, DefaultableField) and id_field.has_default():
                 id_val = id_field.get_default()
-            setattr(self, id_field.attname, id_val)
+            setattr(self, id_field.name, id_val)
         id_set = id_val is not None
         if not id_set and (force_update or update_fields):
             raise ValueError("Cannot force an update in save() with no primary key.")
@@ -488,7 +479,7 @@ class Model(metaclass=ModelBase):
         if id_set and not force_insert:
             base_qs = meta.base_queryset
             values = [
-                (f, (getattr(self, f.attname) if raw else f.pre_save(self, False)))
+                (f, (f.value_from_object(self) if raw else f.pre_save(self, False)))
                 for f in non_pks
             ]
             # DATABASE_DEFAULT fields represent "let the DB produce this on
@@ -497,9 +488,7 @@ class Model(metaclass=ModelBase):
             # below handles them correctly. If the UPDATE *does* succeed, we
             # need to refresh those fields from the DB so the in-memory
             # instance doesn't keep the sentinel.
-            db_default_attnames = [
-                v[0].attname for v in values if v[1] is DATABASE_DEFAULT
-            ]
+            db_default_names = [v[0].name for v in values if v[1] is DATABASE_DEFAULT]
             values = [v for v in values if v[1] is not DATABASE_DEFAULT]
             forced_update = bool(update_fields or force_update)
             updated = self._do_update(
@@ -511,8 +500,8 @@ class Model(metaclass=ModelBase):
                 raise psycopg.DatabaseError(
                     "Save with update_fields did not affect any rows."
                 )
-            if updated and db_default_attnames:
-                self.refresh_from_db(fields=db_default_attnames)
+            if updated and db_default_names:
+                self.refresh_from_db(fields=db_default_names)
         if not updated:
             fields = meta.local_concrete_fields
             if not id_set:
@@ -523,7 +512,8 @@ class Model(metaclass=ModelBase):
             results = self._do_insert(meta.base_queryset, fields, returning_fields, raw)
             if results:
                 for value, field in zip(results[0], returning_fields):
-                    setattr(self, field.attname, value)
+                    assert field.name is not None
+                    setattr(self, field.name, value)
         return updated
 
     def _do_update(
@@ -592,14 +582,16 @@ class Model(metaclass=ModelBase):
                         f"{operation_name}() prohibited to prevent data loss due to unsaved "
                         f"related object '{field.name}'."
                     )
-                elif getattr(self, field.attname) in field.empty_values:
+                elif field.value_from_object(self) in field.empty_values:
                     # 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.
-                if getattr(obj, field.target_field.attname) != getattr(
-                    self, field.attname
+                # 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
                 ):
                     field.delete_cached_value(self)
 
@@ -624,14 +616,16 @@ class Model(metaclass=ModelBase):
         # blocks see the abort state even if the caller catches IntegrityError.
         with transaction.mark_for_rollback_on_error():
             count = self._model_meta.base_queryset.filter(id=self.id)._raw_delete()
-        setattr(self, self._model_meta.get_forward_field("id").attname, None)
+        id_field = self._model_meta.get_forward_field("id")
+        assert id_field.name is not None
+        setattr(self, id_field.name, None)
         return count
 
     def get_field_display(self, field_name: str) -> str:
         """Get the display value for a field, especially useful for fields with choices."""
         # Get the field object from the field name
         field = self._model_meta.get_forward_field(field_name)
-        value = getattr(self, field.attname)
+        value = field.value_from_object(self)
 
         # If field has no choices, just return the value as string
         if not hasattr(field, "flatchoices") or not field.flatchoices:
@@ -650,7 +644,7 @@ class Model(metaclass=ModelBase):
             exclude = set()
         meta = meta or self._model_meta
         return {
-            field.name: Value(getattr(self, field.attname), field)
+            field.name: Value(field.value_from_object(self), field)
             for field in meta.local_concrete_fields
             if field.name not in exclude
         }
@@ -660,7 +654,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().attname)
+        return getattr(self, field.remote_field.get_related_field().name)
 
     def clean(self) -> None:
         """
@@ -722,7 +716,7 @@ class Model(metaclass=ModelBase):
             lookup_kwargs = {}
             for field_name in unique_check:
                 f = self._model_meta.get_forward_field(field_name)
-                lookup_value = getattr(self, f.attname)
+                lookup_value = f.value_from_object(self)
                 if lookup_value is None:
                     # no value, skip the lookup
                     continue
@@ -842,7 +836,7 @@ class Model(metaclass=ModelBase):
         for f in self._model_meta.fields:
             if f.name in exclude:
                 continue
-            if self.__dict__.get(f.attname) is DATABASE_DEFAULT:
+            if self.__dict__.get(f.name) is DATABASE_DEFAULT:
                 exclude.add(f.name)
             elif f.auto_fills_on_save:
                 exclude.add(f.name)
@@ -896,11 +890,11 @@ class Model(metaclass=ModelBase):
                 continue
             # Skip validation for empty fields with required=False. The developer
             # is responsible for making sure they have a valid value.
-            raw_value = getattr(self, f.attname)
+            raw_value = f.value_from_object(self)
             if not f.required and raw_value in f.empty_values:
                 continue
             try:
-                setattr(self, f.attname, f.clean(raw_value, self))
+                setattr(self, f.name, f.clean(raw_value, self))
             except ValidationError as e:
                 errors[f.name] = e.error_list
 
@@ -1000,12 +994,12 @@ class Model(metaclass=ModelBase):
 
     @classmethod
     def _check_field_name_clashes(cls) -> list[PreflightResult]:
-        """Reject fields that share a name or attname within the same model."""
+        """Reject fields that share a name within the same model."""
         errors: list[PreflightResult] = []
-        used_fields = {}  # name or attname -> field
+        used_fields = {}  # name -> field
 
         for f in cls._model_meta.local_fields:
-            clash = used_fields.get(f.name) or used_fields.get(f.attname) or None
+            clash = used_fields.get(f.name)
             # Note that we may detect clash between user-defined non-unique
             # field "id" and automatically added unique field "id", both
             # defined at the same model. This special case is considered in
@@ -1023,7 +1017,6 @@ class Model(metaclass=ModelBase):
                     )
                 )
             used_fields[f.name] = f
-            used_fields[f.attname] = f
 
         return errors
 
@@ -1082,7 +1075,7 @@ class Model(metaclass=ModelBase):
         errors: list[PreflightResult] = []
         property_names = cls._model_meta._property_names
         related_field_accessors = (
-            f.get_attname()
+            f.name
             for f in cls._model_meta._get_fields(reverse=False)
             if isinstance(f, RelatedField)
         )
@@ -1164,8 +1157,6 @@ class Model(metaclass=ModelBase):
         forward_fields_map: dict[str, Field] = {}
         for field in cls._model_meta._get_fields(reverse=False):
             forward_fields_map[field.name] = field
-            if hasattr(field, "attname"):
-                forward_fields_map[field.attname] = field
 
         errors: list[PreflightResult] = []
         for field_name in fields:
@@ -1277,7 +1268,7 @@ class Model(metaclass=ModelBase):
         meta = cls._model_meta
         valid_fields = set(
             chain.from_iterable(
-                (f.name, f.attname)
+                (f.name,)
                 if not (f.auto_created and not f.concrete)
                 else (f.field.related_query_name(),)
                 for f in chain(meta.fields, meta.related_objects)

{plain_postgres-0.103.5 → plain_postgres-0.104.0}/plain/postgres/constraints.py

@@ -363,7 +363,7 @@ class UniqueConstraint(BaseConstraint):
                 if exclude and field_name in exclude:
                     return
                 field = model._model_meta.get_forward_field(field_name)
-                lookup_value = getattr(instance, field.attname)
+                lookup_value = field.value_from_object(instance)
                 if lookup_value is None:
                     # A composite constraint containing NULL value cannot cause
                     # a violation since NULL != NULL in SQL.

{plain_postgres-0.103.5 → plain_postgres-0.104.0}/plain/postgres/fields/base.py

@@ -82,15 +82,12 @@ def _load_field(
 
 # A guide to Field parameters:
 #
-#   * name:      The name of the field specified in the model.
-#   * attname:   The attribute to use on the model object. This is the same as
-#                "name", except in the case of ForeignKeys, where "_id" is
-#                appended.
-#   * column:    The database column for this field. This is the same as
-#                "attname".
-#
-# Code that introspects values, or does other dynamic things, should use
-# attname.
+#   * name:      The name of the field specified in the model. This is also the
+#                attribute and instance __dict__ key for the field's value -- a
+#                foreign key stores its raw key under the field name and is
+#                reached through its descriptor.
+#   * column:    The database column for this field. The same as "name",
+#                except for ForeignKeys, where the "_id" suffix is appended.
 
 
 def _empty(of_cls: type) -> Empty:
@@ -115,7 +112,6 @@ class Field[T](RegisterLookupMixin):
     # Set by __init__
     name: str | None
     # Set by set_attributes_from_name (called by contribute_to_class)
-    attname: str
     column: str
     concrete: bool
     # Set by contribute_to_class
@@ -376,8 +372,9 @@ class Field[T](RegisterLookupMixin):
 
     def set_attributes_from_name(self, name: str) -> None:
         self.name = self.name or name
-        self.attname = self.get_attname()
-        self.column = self.attname
+        # The database column is the field name. A foreign key overrides this
+        # method only to append the "_id" suffix to `column`.
+        self.column = self.name
         self.concrete = self.column is not None
 
     def contribute_to_class(self, cls: type[Model], name: str) -> None:
@@ -394,7 +391,8 @@ class Field[T](RegisterLookupMixin):
         # Field is its own descriptor; make sure it is set on the class so
         # attribute access hits __get__/__set__.
         if self.column:
-            setattr(cls, self.attname, self)
+            assert self.name is not None
+            setattr(cls, self.name, self)
 
     # Descriptor protocol implementation
     @overload
@@ -417,17 +415,25 @@ class Field[T](RegisterLookupMixin):
 
         # If field hasn't been contributed to a class yet (e.g., used standalone
         # as an output_field in aggregates), just return self
-        if not hasattr(self, "attname"):
+        if not hasattr(self, "column"):
             return self
 
         # Instance access - get value from instance dict
+        assert self.name is not None
         data = instance.__dict__
-        field_name = self.attname
+        field_name = self.name
 
-        # If value not in dict, lazy load from database
+        # If value not in dict, lazy load from database. Hydrate every
+        # currently-missing concrete field in one query rather than one query
+        # per field accessed -- this is what makes a foreign key partial
+        # instance cheap to use beyond its primary key.
         if field_name not in data:
-            # Deferred field - load it from the database
-            instance.refresh_from_db(fields=[field_name])
+            missing = [
+                f.name
+                for f in instance._model_meta.concrete_fields
+                if f.name not in data
+            ]
+            instance.refresh_from_db(fields=missing)
 
         return cast(T, data.get(field_name))
 
@@ -436,10 +442,10 @@ class Field[T](RegisterLookupMixin):
         Descriptor __set__ for attribute assignment.
 
         Validates and converts the value using to_python(), then stores it
-        in instance.__dict__[attname].
+        in instance.__dict__[name].
         """
         # Safety check: ensure field has been properly initialized
-        if not hasattr(self, "attname"):
+        if not hasattr(self, "column"):
             raise AttributeError(
                 f"Field {self.__class__.__name__} has not been initialized properly. "
                 f"The field's contribute_to_class() has not been called yet. "
@@ -452,7 +458,8 @@ class Field[T](RegisterLookupMixin):
             value = self.to_python(value)
 
         # Store in instance dict
-        instance.__dict__[self.attname] = value
+        assert self.name is not None
+        instance.__dict__[self.name] = value
 
     def __delete__(self, instance: Model) -> None:
         """
@@ -460,20 +467,18 @@ class Field[T](RegisterLookupMixin):
 
         Removes the value from instance.__dict__.
         """
+        assert self.name is not None
         try:
-            del instance.__dict__[self.attname]
+            del instance.__dict__[self.name]
         except KeyError:
             raise AttributeError(
-                f"{instance.__class__.__name__!r} object has no attribute {self.attname!r}"
+                f"{instance.__class__.__name__!r} object has no attribute {self.name!r}"
             )
 
-    def get_attname(self) -> str:
-        assert self.name is not None  # Field name must be set
-        return self.name
-
     def pre_save(self, model_instance: Model, add: bool) -> T | None:
         """Return field's value just before saving."""
-        return getattr(model_instance, self.attname)
+        assert self.name is not None
+        return getattr(model_instance, self.name)
 
     def get_prep_value(self, value: Any) -> Any:
         """Perform preliminary non-db specific value checks and conversions."""
@@ -530,7 +535,8 @@ class Field[T](RegisterLookupMixin):
 
     def value_from_object(self, obj: Model) -> T | None:
         """Return the value of this field in the given model instance."""
-        return getattr(obj, self.attname)
+        assert self.name is not None
+        return getattr(obj, self.name)
 
 
 class ColumnField[T](Field[T]):