SQLAlchemy Migration Guides
The string backref pattern still works but explicit back_populates is the modern approach.
Start here
Keep backref if it works, or convert to explicit back_populates on both sides when the migration also touches the relationship.
Stop before automation when: Complex relationship inheritance. backref() with custom arguments.
class User(Base):
orders = relationship("Order", back_populates="user")
class Order(Base):
user = relationship("User", back_populates="orders")
Repo fit check
Run the matching scanner locally first. Read the free findings and manual alternatives; consider paid cleanup only if supported patterns repeat enough to justify the price.
Example scan summary
supported_findings: 38
manual_review_findings: 6
files_uploaded: 0
confidence: reviewableWhy this page exists
String backref is legacy. Explicit back_populates is cleaner for migration.
Direct answer
Keep backref if it works, or convert to explicit back_populates on both sides when the migration also touches the relationship.
Example
class User(Base):
orders = relationship("Order", backref="user")
class User(Base):
orders = relationship("Order", back_populates="user")
class Order(Base):
user = relationship("User", back_populates="orders")
Decision path
Start with the free scan, inspect the report, and only move to the cleanup pack if the repo has repeated supported patterns that are still expensive to fix by hand.
Before checkout
Price: $299.99 per team.
Use the exact-problem guides as a triage layer, then decide whether the repo is inside the supported subset.
FAQ
Keep backref if it works, or convert to explicit back_populates on both sides when the migration also touches the relationship.
Automate only the supported subset: Detection of string backref usage. Reporting for where backref still appears. Cross-links to the string loader cleanup pages. Keep these cases in manual review: Complex relationship inheritance. backref() with custom arguments. Files where both sides are not easily accessible.
Use SQLAlchemy 1.4 to 2.0 Migration Cleanup Pack only when this pattern repeats across enough files that manual cleanup is still costly. Use the free report and upstream guide to evaluate fit. Buy only if repeated supported edits justify the price; no paid assessment is required.
Purchase fit
One matching page is not enough by itself. Run the local scan, then buy only when the same supported pattern appears often enough to matter.
Replace session.query(...).get(...), Session.query migration guide, Fix engine.execute(...) removal, Clean up joinedload_all(...), Fix select([..]) list syntax, Replace string join paths, Replace string loader options, Move sqlalchemy.ext.declarative imports to sqlalchemy.orm
View all SQLAlchemy 1.4 to 2.0 Migration Cleanup Pack guides