Migrating from SQLAlchemy 1.4 to 2.0

Learn how to migrate SQLAlchemy 1.4 codebases to 2.0 using Codegen

Migrating from SQLAlchemy 1.4 to 2.0 involves several API changes to support the new 2.0-style query interface. This guide will walk you through using Graph-sitter to automate this migration, handling query syntax, session usage, and ORM patterns.

You can find the complete example code in our examples repository.

Overview

The migration process involves three main steps:

1. Converting legacy Query objects to select() statements
2. Updating session execution patterns
3. Modernizing ORM relationship declarations

Let’s walk through each step using Codegen.

Step 1: Convert Query to Select

First, we need to convert legacy Query-style operations to the new select() syntax:

def convert_query_to_select(file):
    """Convert Query-style operations to select() statements"""
    for call in file.function_calls:
        if call.name == "query":
            # Convert query(Model) to select(Model)
            call.set_name("select")

            # Update method chains
            if call.parent and call.parent.is_method_chain:
                chain = call.parent
                if "filter" in chain.source:
                    # Convert .filter() to .where()
                    chain.source = chain.source.replace(".filter(", ".where(")
                if "filter_by" in chain.source:
                    # Convert .filter_by(name='x') to .where(Model.name == 'x')
                    model = call.args[0].value
                    conditions = chain.source.split("filter_by(")[1].split(")")[0]
                    new_conditions = []
                    for cond in conditions.split(","):
                        if "=" in cond:
                            key, value = cond.split("=")
                            new_conditions.append(f"{model}.{key.strip()} == {value.strip()}")
                    chain.edit(f".where({' & '.join(new_conditions)})")

This transforms code from:

# Legacy Query style
session.query(User).filter_by(name='john').filter(User.age >= 18).all()

to:

# New select() style
session.execute(
    select(User).where(User.name == 'john').where(User.age >= 18)
).scalars().all()

SQLAlchemy 2.0 standardizes on select() statements for all queries, providing better type checking and a more consistent API.

Step 2: Update Session Execution

Next, we update how queries are executed with the Session:

def update_session_execution(file):
    """Update session execution patterns for 2.0 style"""
    for call in file.function_calls:
        if call.name == "query":
            # Find the full query chain
            chain = call
            while chain.parent and chain.parent.is_method_chain:
                chain = chain.parent

            # Wrap in session.execute() if needed
            if not chain.parent or "execute" not in chain.parent.source:
                chain.edit(f"execute(select{chain.source[5:]})")

            # Add .scalars() for single-entity queries
            if len(call.args) == 1:
                chain.edit(f"{chain.source}.scalars()")

This converts patterns like:

# Old style
users = session.query(User).all()
first_user = session.query(User).first()

to:

# New style
users = session.execute(select(User)).scalars().all()
first_user = session.execute(select(User)).scalars().first()

The new execution pattern is more explicit about what’s being returned, making it easier to understand and maintain type safety.

Step 3: Update ORM Relationships

Finally, we update relationship declarations to use the new style: