1107 Fix prefetch when a ForeignKey has db_column_name set (#1111)

* fix prefetch when a `ForeignKey` has `db_column_name` set

* Update run.py

* add Signing table

* add option to match on db_column_name

* add a test

* Revert "fix prefetch when a `ForeignKey` has `db_column_name` set"

This reverts commit 2de72c7.

* sort imports

* Update run.py

* Update test_apps.py

* Update test_run.py

* Create music_2026_02_22t00_41_01_493867.py

* Update test_forwards_backwards.py

* fix linter warning

Author: dantownsend

piccolo/apps/playground/commands/run.py

@@ -25,6 +25,7 @@
     Serial,
     Text,
     Timestamp,
+    Timestamptz,
     Varchar,
 )
 from piccolo.columns.readable import Readable
@@ -184,6 +185,13 @@ class GenreToBand(Table):
     reason = Text(null=True, default=None)
 
 
+class Signing(Table):
+    id: Serial
+    address = Text()
+    with_ = ForeignKey(Band, db_column_name="with")
+    starts = Timestamptz()
+
+
 TABLES = (
     Manager,
     Band,
@@ -196,6 +204,7 @@ class GenreToBand(Table):
     Album,
     Genre,
     GenreToBand,
+    Signing,
 )
 
 
@@ -334,6 +343,19 @@ def populate():
         GenreToBand(band=c_sharps.id, genre=genres[1]["id"]),
     ).run_sync()
 
+    Signing.insert(
+        Signing(
+            with_=pythonistas,
+            address="Awesome Music Store, London",
+            starts=datetime.datetime(2026, 12, 20, 10),
+        ),
+        Signing(
+            with_=pythonistas,
+            address="Awesome Music Store, Liverpool",
+            starts=datetime.datetime(2026, 11, 25, 12),
+        ),
+    ).run_sync()
+
 
 def run(
     engine: str = "sqlite",

piccolo/table.py

@@ -149,18 +149,38 @@ def refresh_db(self) -> None:
             raise ValueError("The engine can't be found")
         self.db = engine
 
-    def get_column_by_name(self, name: str) -> Column:
+    def get_column_by_name(
+        self,
+        name: str,
+        match_db_column_name: bool = False,
+    ) -> Column:
         """
         Returns a column which matches the given name. It will try and follow
         foreign keys too, for example if the name is 'foo.bar', where foo is
         a foreign key, and bar is a column on the referenced table.
+
+        :param match_db_column_name:
+            If ``True``, we also check the column's ``db_column_name`` for a
+            match.
+
         """
         components = name.split(".")
         column_name = components[0]
-        column = [i for i in self.columns if i._meta.name == column_name]
-        if len(column) != 1:
+        column_object = next(
+            (
+                i
+                for i in self.columns
+                if (i._meta.name == column_name)
+                or (
+                    i._meta.db_column_name == column_name
+                    if match_db_column_name
+                    else False
+                )
+            ),
+            None,
+        )
+        if column_object is None:
             raise ValueError(f"No matching column found with name == {name}")
-        column_object = column[0]
 
         if len(components) > 1:
             for reference_name in components[1:]:

piccolo/utils/objects.py

@@ -41,7 +41,10 @@ def make_nested_object(row: dict[str, Any], table_class: type[Table]) -> Table:
     for key, value in row.items():
         if isinstance(value, dict):
             # This is probably a related table.
-            fk_column = table_class._meta.get_column_by_name(key)
+            fk_column = table_class._meta.get_column_by_name(
+                key,
+                match_db_column_name=True,
+            )
 
             if isinstance(fk_column, ForeignKey):
                 related_table_class = (

tests/apps/migrations/commands/test_forwards_backwards.py

@@ -18,6 +18,7 @@
     Poster,
     RecordingStudio,
     Shirt,
+    Signing,
     Ticket,
     Venue,
 )
@@ -35,6 +36,7 @@
     Shirt,
     RecordingStudio,
     Instrument,
+    Signing,
 ]
 
 
@@ -215,6 +217,7 @@ def test_forwards_fake(self):
                 "2021-11-13T14:01:46:114725",
                 "2024-05-28T23:15:41:018844",
                 "2024-06-19T18:11:05:793132",
+                "2026-02-22T00:41:01:493867",
             ],
         )
 

tests/apps/shell/commands/test_run.py

@@ -25,6 +25,7 @@ def test_run(self, print_: MagicMock, start_ipython_shell: MagicMock):
                 call("- Poster"),
                 call("- RecordingStudio"),
                 call("- Shirt"),
+                call("- Signing"),
                 call("- Ticket"),
                 call("- Venue"),
                 call("Importing mega tables:"),

tests/conf/test_apps.py

@@ -21,6 +21,7 @@
     Poster,
     RecordingStudio,
     Shirt,
+    Signing,
     Ticket,
     Venue,
 )
@@ -126,6 +127,7 @@ def test_table_finder(self):
                 "Poster",
                 "RecordingStudio",
                 "Shirt",
+                "Signing",
                 "Ticket",
                 "Venue",
             ],
@@ -153,6 +155,7 @@ def test_table_finder_coercion(self):
                 "Poster",
                 "RecordingStudio",
                 "Shirt",
+                "Signing",
                 "Ticket",
                 "Venue",
             ],
@@ -196,6 +199,7 @@ def test_exclude_tags(self):
                 "Manager",
                 "RecordingStudio",
                 "Shirt",
+                "Signing",
                 "Ticket",
                 "Venue",
             ],
@@ -245,6 +249,7 @@ def test_get_table_classes(self):
                 Poster,
                 RecordingStudio,
                 Shirt,
+                Signing,
                 SmallTable,
                 Ticket,
                 Venue,
@@ -264,6 +269,7 @@ def test_get_table_classes(self):
                 Poster,
                 RecordingStudio,
                 Shirt,
+                Signing,
                 Ticket,
                 Venue,
             ],

tests/conftest.py

@@ -20,6 +20,7 @@ async def drop_tables():
         "instrument",
         "shirt",
         "instrument",
+        "signing",
         "mega_table",
         "small_table",
     ]

tests/example_apps/music/piccolo_migrations/music_2026_02_22t00_41_01_493867.py

@@ -0,0 +1,102 @@
+from piccolo.apps.migrations.auto.migration_manager import MigrationManager
+from piccolo.columns.base import OnDelete, OnUpdate
+from piccolo.columns.column_types import ForeignKey, Serial, Text, Timestamptz
+from piccolo.columns.defaults.timestamptz import TimestamptzNow
+from piccolo.columns.indexes import IndexMethod
+from piccolo.table import Table
+
+
+class Band(Table, tablename="band", schema=None):
+    id = Serial(
+        null=False,
+        primary_key=True,
+        unique=False,
+        index=False,
+        index_method=IndexMethod.btree,
+        choices=None,
+        db_column_name="id",
+        secret=False,
+    )
+
+
+ID = "2026-02-22T00:41:01:493867"
+VERSION = "1.32.0"
+DESCRIPTION = "Add Signing table"
+
+
+async def forwards():
+    manager = MigrationManager(
+        migration_id=ID, app_name="music", description=DESCRIPTION
+    )
+
+    manager.add_table(
+        class_name="Signing", tablename="signing", schema=None, columns=None
+    )
+
+    manager.add_column(
+        table_class_name="Signing",
+        tablename="signing",
+        column_name="address",
+        db_column_name="address",
+        column_class_name="Text",
+        column_class=Text,
+        params={
+            "default": "",
+            "null": False,
+            "primary_key": False,
+            "unique": False,
+            "index": False,
+            "index_method": IndexMethod.btree,
+            "choices": None,
+            "db_column_name": None,
+            "secret": False,
+        },
+        schema=None,
+    )
+
+    manager.add_column(
+        table_class_name="Signing",
+        tablename="signing",
+        column_name="with_",
+        db_column_name="with",
+        column_class_name="ForeignKey",
+        column_class=ForeignKey,
+        params={
+            "references": Band,
+            "on_delete": OnDelete.cascade,
+            "on_update": OnUpdate.cascade,
+            "target_column": None,
+            "null": True,
+            "primary_key": False,
+            "unique": False,
+            "index": False,
+            "index_method": IndexMethod.btree,
+            "choices": None,
+            "db_column_name": "with",
+            "secret": False,
+        },
+        schema=None,
+    )
+
+    manager.add_column(
+        table_class_name="Signing",
+        tablename="signing",
+        column_name="starts",
+        db_column_name="starts",
+        column_class_name="Timestamptz",
+        column_class=Timestamptz,
+        params={
+            "default": TimestamptzNow(),
+            "null": False,
+            "primary_key": False,
+            "unique": False,
+            "index": False,
+            "index_method": IndexMethod.btree,
+            "choices": None,
+            "db_column_name": None,
+            "secret": False,
+        },
+        schema=None,
+    )
+
+    return manager

tests/example_apps/music/tables.py

@@ -9,6 +9,7 @@
     Numeric,
     Serial,
     Text,
+    Timestamptz,
     Varchar,
 )
 from piccolo.columns.readable import Readable
@@ -125,3 +126,14 @@ class Instrument(Table):
     id: Serial
     name = Varchar()
     recording_studio = ForeignKey(RecordingStudio)
+
+
+class Signing(Table):
+    """
+    Used for testing ``db_column_name``.
+    """
+
+    id: Serial
+    address = Text()
+    with_ = ForeignKey(Band, db_column_name="with")
+    starts = Timestamptz()

tests/table/test_join.py

@@ -6,6 +6,7 @@
     Band,
     Concert,
     Manager,
+    Signing,
     Ticket,
     Venue,
 )
@@ -23,7 +24,7 @@ def test_create_join(self):
 
 
 class TestJoin(TestCase):
-    tables = [Manager, Band, Venue, Concert, Ticket]
+    tables = [Manager, Band, Venue, Concert, Ticket, Signing]
 
     def setUp(self):
         for table in self.tables:
@@ -52,6 +53,9 @@ def setUp(self):
         ticket = Ticket(concert=concert, price=decimal.Decimal(50.0))
         ticket.save().run_sync()
 
+        signing = Signing(with_=band_1)
+        signing.save().run_sync()
+
     def tearDown(self):
         for table in reversed(self.tables):
             table.alter().drop_table().run_sync()
@@ -486,3 +490,15 @@ def test_objects_prefetch_multiple_intermediate(self):
 
         self.assertIsInstance(ticket.concert.band_2.manager.id, int)
         self.assertIsInstance(ticket.concert.band_2.manager.name, str)
+
+    def test_objects_prefetch_db_column_name(self):
+        """
+        Make sure that ``prefetch`` works with foreign keys with
+        ``db_column_name`` defined.
+
+        https://github.com/piccolo-orm/piccolo/issues/1107
+
+        """
+        signing = Signing.objects().prefetch(Signing.with_).first().run_sync()
+        assert signing is not None
+        self.assertIsInstance(signing.with_, Band)