Better relationship naming (#453)

sheinbergon · agronholm · web-flow · commit bdcc4b8232ca · 2026-02-04T00:37:55.000+02:00
* Better relationship naming * Better changes descriptions * Better changes descriptions * Reformatted the changelog entry Updated version header and improved formatting for clarity. * Update src/sqlacodegen/generators.py Co-authored-by: Alex Grönholm <alex.gronholm@nextday.fi> * Support Multiple MANY2MANY * Support Multiple MANY2MANY - Attempt #2 * Support Multiple MANY2MANY - Attempt #3 * Code cleanup * Properly support multiple M2M relationship * Remove comments * Some tidying up --------- Co-authored-by: Alex Grönholm <alex.gronholm@nextday.fi>
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,6 +1,14 @@
 Version history
 ===============
 
+**UNRELEASED**
+
+- **BACKWARD INCOMPATIBLE** Relationship names changed when multiple FKs or junction tables
+  connect to the same target table. Regenerating models will break existing code.
+- Improved relationship naming: one-to-many uses FK column names (e.g.,
+  ``simple_items_parent_container``), many-to-many uses junction table names (e.g.,
+  ``students_enrollments``). Use ``--options nofknames`` to revert to old behavior.
+
 **4.0.0rc2**
 
 - Add ``values_callable`` lambda to generated native enums column definitions.
diff --git a/README.rst b/README.rst
@@ -122,6 +122,11 @@ values must be delimited by commas, e.g. ``--options noconstraints,nobidi``):
   * ``nobidi``: generate relationships in a unidirectional fashion, so only the
     many-to-one or first side of many-to-many relationships gets a relationship
     attribute, as on v2.X
+  * ``nofknames``: disable improved relationship naming when multiple FKs or
+    junction tables connect to the same target. By default, uses FK column names
+    for one-to-many (e.g., ``simple_items_parent_container``) and junction table
+    names for many-to-many (e.g., ``students_enrollments``). Reverts to
+    underscore suffixes (``simple_items_``, ``student_``).
 
 * ``dataclasses``
 
@@ -189,6 +194,14 @@ due to that ``_id`` suffix.
 For self referential relationships, the reverse side of the relationship will be named
 with the ``_reverse`` suffix appended to it.
 
+When multiple foreign keys or junction tables connect to the same target table,
+relationships use qualifiers for disambiguation. One-to-many relationships use FK
+column names (e.g., ``simple_items_parent_container``, ``simple_items_top_container``).
+Many-to-many relationships use junction table names (e.g., ``students_enrollments``,
+``students_waitlist``), except for self-referential cases which use FK column names
+(e.g., ``parent``, ``child``). The ``nofknames`` option reverts to underscore suffixes
+(``simple_items_``, ``student_``).
+
 Customizing code generation logic
 =================================
 
diff --git a/src/sqlacodegen/generators.py b/src/sqlacodegen/generators.py
@@ -969,6 +969,7 @@ class DeclarativeGenerator(TablesGenerator):
         "nojoined",
         "nobidi",
         "noidsuffix",
+        "nofknames",
     }
 
     def __init__(
@@ -1290,43 +1291,149 @@ def generate_relationship_name(
         global_names: set[str],
         local_names: set[str],
     ) -> None:
-        # Self referential reverse relationships
-        preferred_name: str
-        if (
-            relationship.type
-            in (RelationshipType.ONE_TO_MANY, RelationshipType.ONE_TO_ONE)
-            and relationship.source is relationship.target
-            and relationship.backref
-            and relationship.backref.name
-        ):
-            preferred_name = relationship.backref.name + "_reverse"
-        else:
-            preferred_name = relationship.target.table.name
+        def strip_id_suffix(name: str) -> str:
+            # Strip _id only if at the end or followed by underscore (e.g., "course_id" -> "course", "course_id_1" -> "course_1")
+            # But don't strip from "parent_id1" (where id is followed by a digit without underscore)
+            return re.sub(r"_id(?=_|$)", "", name)
+
+        def get_m2m_qualified_name(default_name: str) -> str:
+            """Generate qualified name for many-to-many relationship when multiple junction tables exist."""
+            # Check if there are multiple M2M relationships to the same target
+            target_m2m_relationships = [
+                r
+                for r in relationship.source.relationships
+                if r.target is relationship.target
+                and r.type == RelationshipType.MANY_TO_MANY
+            ]
+
+            # Only use junction-based naming when there are multiple M2M to same target
+            if len(target_m2m_relationships) > 1:
+                if relationship.source is relationship.target:
+                    # Self-referential: use FK column name from junction table
+                    # (e.g., "parent_id" -> "parent", "child_id" -> "child")
+                    if relationship.constraint:
+                        column_names = [c.name for c in relationship.constraint.columns]
+                        if len(column_names) == 1:
+                            fk_qualifier = strip_id_suffix(column_names[0])
+                        else:
+                            fk_qualifier = "_".join(
+                                strip_id_suffix(col_name) for col_name in column_names
+                            )
+                        return fk_qualifier
+                elif relationship.association_table:
+                    # Normal: use junction table name as qualifier
+                    junction_name = relationship.association_table.table.name
+                    fk_qualifier = strip_id_suffix(junction_name)
+                    return f"{relationship.target.table.name}_{fk_qualifier}"
+            else:
+                # Single M2M: use simple name from junction table FK column
+                # (e.g., "right_id" -> "right" instead of "right_table")
+                if relationship.constraint and "noidsuffix" not in self.options:
+                    column_names = [c.name for c in relationship.constraint.columns]
+                    if len(column_names) == 1:
+                        stripped_name = strip_id_suffix(column_names[0])
+                        if stripped_name != column_names[0]:
+                            return stripped_name
+
+            return default_name
+
+        def get_fk_qualified_name(constraint: ForeignKeyConstraint) -> str:
+            """Generate qualified name for one-to-many/one-to-one relationship using FK column names."""
+            column_names = [c.name for c in constraint.columns]
+
+            if len(column_names) == 1:
+                # Single column FK: strip _id suffix if present
+                fk_qualifier = strip_id_suffix(column_names[0])
+            else:
+                # Multi-column FK: concatenate all column names (strip _id from each)
+                fk_qualifier = "_".join(
+                    strip_id_suffix(col_name) for col_name in column_names
+                )
 
-            # If there's a constraint with a single column that ends with "_id", use the
-            # preceding part as the relationship name
-            if relationship.constraint and "noidsuffix" not in self.options:
+            # For self-referential relationships, don't prepend the table name
+            if relationship.source is relationship.target:
+                return fk_qualifier
+            else:
+                return f"{relationship.target.table.name}_{fk_qualifier}"
+
+        def resolve_preferred_name() -> str:
+            resolved_name = relationship.target.table.name
+
+            # For reverse relationships with multiple FKs to the same table, use the FK
+            # column name to create a more descriptive relationship name
+            # For M2M relationships with multiple junction tables, use the junction table name
+            use_fk_based_naming = "nofknames" not in self.options and (
+                (
+                    relationship.constraint
+                    and relationship.type
+                    in (RelationshipType.ONE_TO_MANY, RelationshipType.ONE_TO_ONE)
+                    and relationship.foreign_keys
+                )
+                or (
+                    relationship.type == RelationshipType.MANY_TO_MANY
+                    and relationship.association_table
+                )
+            )
+
+            if use_fk_based_naming:
+                if relationship.type == RelationshipType.MANY_TO_MANY:
+                    resolved_name = get_m2m_qualified_name(resolved_name)
+                elif relationship.constraint:
+                    resolved_name = get_fk_qualified_name(relationship.constraint)
+
+            # If there's a constraint with a single column that contains "_id", use the
+            # stripped version as the relationship name
+            elif relationship.constraint and "noidsuffix" not in self.options:
                 is_source = relationship.source.table is relationship.constraint.table
                 if is_source or relationship.type not in (
                     RelationshipType.ONE_TO_ONE,
                     RelationshipType.ONE_TO_MANY,
                 ):
                     column_names = [c.name for c in relationship.constraint.columns]
-                    if len(column_names) == 1 and column_names[0].endswith("_id"):
-                        preferred_name = column_names[0][:-3]
+                    if len(column_names) == 1:
+                        stripped_name = strip_id_suffix(column_names[0])
+                        # Only use the stripped name if it actually changed (had _id in it)
+                        if stripped_name != column_names[0]:
+                            resolved_name = stripped_name
+                    else:
+                        # For composite FKs, check if there are multiple FKs to the same target
+                        target_relationships = [
+                            r
+                            for r in relationship.source.relationships
+                            if r.target is relationship.target
+                            and r.type == relationship.type
+                        ]
+                        if len(target_relationships) > 1:
+                            # Multiple FKs to same table - use concatenated column names
+                            resolved_name = "_".join(
+                                strip_id_suffix(col_name) for col_name in column_names
+                            )
 
             if "use_inflect" in self.options:
                 inflected_name: str | Literal[False]
                 if relationship.type in (
                     RelationshipType.ONE_TO_MANY,
                     RelationshipType.MANY_TO_MANY,
                 ):
-                    if not self.inflect_engine.singular_noun(preferred_name):
-                        preferred_name = self.inflect_engine.plural_noun(preferred_name)
+                    if not self.inflect_engine.singular_noun(resolved_name):
+                        resolved_name = self.inflect_engine.plural_noun(resolved_name)
                 else:
-                    inflected_name = self.inflect_engine.singular_noun(preferred_name)
+                    inflected_name = self.inflect_engine.singular_noun(resolved_name)
                     if inflected_name:
-                        preferred_name = inflected_name
+                        resolved_name = inflected_name
+
+            return resolved_name
+
+        if (
+            relationship.type
+            in (RelationshipType.ONE_TO_MANY, RelationshipType.ONE_TO_ONE)
+            and relationship.source is relationship.target
+            and relationship.backref
+            and relationship.backref.name
+        ):
+            preferred_name = relationship.backref.name + "_reverse"
+        else:
+            preferred_name = resolve_preferred_name()
 
         relationship.name = self.find_free_name(
             preferred_name, global_names, local_names
diff --git a/tests/test_generator_declarative.py b/tests/test_generator_declarative.py
