Flask-SQLAlchemy backref function and backref parameter

Question

In Flask-SQLAlchemy, the backref parameter in relationship method allows you to declare a new property under a specified class as seen in the example in their docs:

class Person(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50))
    addresses = db.relationship('Address', backref='person', lazy='dynamic')

class Address(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    email = db.Column(db.String(50))
    person_id = db.Column(db.Integer, db.ForeignKey('person.id'))

But then there is also a backref function:

class User(db.Model):
    id = db.Column(db.Integer, primary_key=True)
    name = db.Column(db.String(50))
    addresses = db.relationship('Address',
                                backref=db.backref('person', lazy='joined'), 
                                lazy='dynamic')

In this case, what's the role of the backref function passed to the backref parameter, especially with the multiple lazy definitions? How is it different from backref='person'?

Using the backref object you can change the behaviour/configuration of the back reference relationship. In your case Address.person has joined loading configured. When you pass just a string, you get the defaults. — Ilja Everilä
@IljaEverilä Doesn't lazy='dynamic' also change the loading configuration? I think this is what is confusing me — kentwait
Yes. It changes the configuration of the relationship the keyword argument is passed to. In your case User.addresses. — Ilja Everilä
Using backref just automates the creation of a relationship property at the other end. backref='person' is somewhat akin to having person = db.relationship('Person') explicitly in the Address class (+ back population). Using the backref() object you can pass arguments to that relationship. — Ilja Everilä

Ricky Han Ricky Han · Accepted Answer · 2017-06-14T08:05:32

From the documentation for Flask models:

backref is a simple way to also declare a new property on the Address class. You can then also use my_address.person to get to the person at that address. lazy defines when SQLAlchemy will load the data from the database:

select (which is the default) means that SQLAlchemy will load the data as necessary in one go using a standard select statement.

joined tells SQLAlchemy to load the relationship in the same query as the parent using a JOIN statement.

subquery works like 'joined' but instead, SQLAlchemy will use a subquery.

dynamic is special and useful if you have many items. Instead of loading the items SQLAlchemy will return another query object which you can further refine before loading the items. This is usually what you want if you expect more than a handful of items for this relationship.

Flask-SQLAlchemy backref function and backref parameter

2 Answers