90

Can anyone explain the concepts of these two ideas and how they relate to making relationships between tables? I can't really seem to find anything that explains it clearly and the documentation feels like there's too much jargon to understand in easy concepts. For instance, in this example of a one to many relationship in the documentation:

class Parent(Base):
    __tablename__ = 'parent'
    id = Column(Integer, primary_key=True)
    children = relationship("Child", back_populates="parent")

class Child(Base):
    __tablename__ = 'child'
    id = Column(Integer, primary_key=True)
    parent_id = Column(Integer, ForeignKey('parent.id'))
    parent = relationship("Parent", back_populates="children")

Why does the relationship() go inside the parent class while ForeignKey goes inside the child class? And what does having back_populates exactly do to one another? Does having the placement of which class the relationship() function exist in matter?

BoopityBoppity
  • 929
  • 2
  • 9
  • 11
  • 2
    http://docs.sqlalchemy.org/en/latest/orm/backref.html – Ilja Everilä Jul 14 '18 at 10:49
  • Possible duplicate of [When do I need to use sqlalchemy back\_populates?](https://stackoverflow.com/questions/39869793/when-do-i-need-to-use-sqlalchemy-back-populates) – Samuel Harmer Aug 04 '18 at 10:55
  • 4
    "there's too much jargon to understand in easy concepts", well said – pcko1 Jan 16 '22 at 22:57
  • 1
    As of July 2022, `backref` is considered legacy and `back_populates` is preferred. – Gord Thompson Jul 12 '22 at 14:17
  • I agree that the documentation is absurdly jargon-heavy. – Stonecraft Jul 17 '22 at 10:34
  • @GordThompson, but the current documentation recommends both without mention of one being preferred over the other, implying that they have different purposes: https://docs.sqlalchemy.org/en/14/orm/basic_relationships.html – Stonecraft Jul 17 '22 at 10:36
  • 1
    @Stonecraft - We are in the process of updating the documentation, e.g., [here](https://docs.sqlalchemy.org/en/14/orm/backref.html) – Gord Thompson Jul 17 '22 at 11:49

2 Answers2

150

backref is a shortcut for configuring both parent.children and child.parent relationships at one place only on the parent or the child class (not both). That is, instead of having 

children = relationship("Child", back_populates="parent")  # on the parent class

and

parent = relationship("Parent", back_populates="children")  # on the child class

you only need one of this: 

children = relationship("Child", backref="parent")  # only on the parent class

or

parent = relationship("Parent", backref="children")  # only on the child class

children = relationship("Child", backref="parent") will create the .parent relationship on the child class automatically. On the other hand, if you use back_populates you must explicitly create the relationships in both parent and child classes.

Why does the relationship() go inside the parent class while ForeignKey goes inside the child class?

As I said above, if you use back_populates, it needs to go on both parent and child classes. If you use backref, it needs to go on one of them only. ForeignKey needs to go on the child class, no matter where the relationship is placed, this is a fundamental concept of relational databases.

And what does having back_populates exactly do to one another?

back_populates informs each relationship about the other, so that they are kept in sync. For example if you do

p1 = Parent()
c1 = Child()
p1.children.append(c1)
print(p1.children)  # will print a list of Child instances with one element: c1
print(c1.parent)  # will print Parent instance: p1

As you can see, p1 was set as parent of c1 even when you didn't set it explicitly.

Does having the placement of which class the relationship() function exist in matter?

This only applies to backref, and no, you can place the relationship on the parent class (children = relationship("Child", backref="parent")) or on the child class (parent = relationship("Parent", backref="children")) and have the exact same effect.

eRunner
  • 1,710
  • 1
  • 11
  • 11
  • 2
    Placing backref decides the "one" side of the one-to-many relationship doesn't it? – Shivansh Jagga Jul 12 '20 at 09:18
  • 1
    Which is better practice currently? I kinda like backref only cos it reads better in a way... – Zaffer Jun 29 '21 at 15:22
  • 2
    @Zaffer Back_populates is actually better to understand, because you see on both tables what their relationships are. If you only use backref, you won't see what other tables relate to the parent if you had it declared only on the child and vice versa. – Thorka Mae Mar 31 '22 at 12:44
  • 9
    @Zaffer re: "Which is better practice currently?" - As of July 2022, `backref` is [considered legacy](https://docs.sqlalchemy.org/en/14/orm/backref.html) and `back_populates` is preferred. – Gord Thompson Jul 12 '22 at 14:16
  • @GordThompson THIS! This is gold! The anwer above is very helpful, and your conclusion is the great final touch! – William Le Sep 09 '22 at 15:21
11

Apparently, use of back_populates with explicit relationship() constructs should be preferred as explained at:

https://docs.sqlalchemy.org/en/14/orm/backref.html

ggorlen
  • 44,755
  • 7
  • 76
  • 106
u2gilles
  • 6,888
  • 7
  • 51
  • 75
  • 1
    Yes. It also makes it easier to understand the code when the relations are defined on both the parent and child models. – Sinan Apr 20 '23 at 16:36