Relationship with nullable forward reference (TYPE_CHECKING) fails on Python 3.14 (PEP 649)

[romver2002]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the SQLModel documentation, with the integrated search.
• I already searched in Google "How to X in SQLModel" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to SQLModel but to Pydantic.
• I already checked if it is not related to SQLModel but to SQLAlchemy.

Commit to Help

• I commit to help with one of those options 👆

Example Code

# reproducer_schedule.py
from sqlmodel import Field, SQLModel


class Schedule(SQLModel, table=True):
    __tablename__ = "schedules"
    id: int | None = Field(default=None, primary_key=True)
    schedule_date: str


# reproducer.py
from typing import TYPE_CHECKING

from sqlalchemy.orm import RelationshipProperty
from sqlmodel import Field, Relationship, SQLModel

if TYPE_CHECKING:
    from reproducer_schedule import Schedule


class ParentBase(SQLModel):
    name: str


class Parent(ParentBase, table=True):
    __tablename__ = "parents"
    id: int | None = Field(default=None, primary_key=True)
    schedule: Schedule | None = Relationship(
        sa_relationship=RelationshipProperty(
            "Schedule",
            uselist=False,
            viewonly=True,
            primaryjoin="Parent.schedule_id == Schedule.id",
        ),
    )
    schedule_id: int | None = Field(default=None, foreign_key="schedules.id")

Description

When using Relationship fields with models imported under TYPE_CHECKING (common pattern for circular imports), SQLModel fails on Python 3.14 due to incompatible handling of PEP 649 deferred annotations in _compat.py.

Root cause

In sqlmodel/_compat.py, the get_annotations() function calls:

raw_annotations = call_annotate_function(annotate, format=Format.FORWARDREF)

With Python 3.14's PEP 649, call_annotate_function internally falls back to Format.VALUE_WITH_FAKE_GLOBALS, which executes the annotation expressions. For nullable relationships with forward references, this creates issues:

Annotation | What happens | Result -- | -- | -- schedule: Schedule \| None | ForwardRef("Schedule") \| None returned | TypeError: unsupported operand type(s) for \|: 'ForwardRef' and 'NoneType' schedule: "Schedule" \| None | Python evaluates str.__or__(NoneType) | TypeError: unsupported operand type(s) for \|: 'str' and 'NoneType' schedule: "Schedule \| None" | String literal passed through | Works (current workaround)

Why this worked before Python 3.14

Before Python 3.14, projects used from __future__ import annotations (PEP 563) which turned all annotations into strings. typing.get_type_hints() resolved them lazily after all modules were loaded. Python 3.14 deprecated PEP 563 in favor of PEP 649, but SQLModel's _compat.py doesn't fully handle the new ForwardRef objects.

Current workaround

Wrap the entire annotation in quotes:

schedule: "Schedule | None" = Relationship(...)

Suggested fix

In _compat.py, the get_annotations() function should handle ForwardRef objects in union types returned by call_annotate_function, similar to how get_relationship_to() already does:

if isinstance(use_annotation, ForwardRef):
    use_annotation = use_annotation.__forward_arg__

Operating System

Linux, Windows

Operating System Details

No response

SQLModel Version

0.0.34

Python Version

3.14

Additional Context

Related FastAPI discussion with a similar fix: fastapi/fastapi#14784
SQLAlchemy 2.0.39+ already fixed their PEP 649 compatibility, but SQLModel has its own annotation processing layer in _compat.py

[romver2002]

Full traceback

File "sqlmodel/main.py", line 550, in __new__
    original_annotations = get_annotations(class_dict)
File "sqlmodel/_compat.py", line 110, in get_annotations
    raw_annotations = call_annotate_function(annotate, format=Format.FORWARDREF)
File "annotationlib.py", line 820, in call_annotate_function
    result = func(Format.VALUE_WITH_FAKE_GLOBALS)
File "reproducer.py", line 23, in __annotate__
    schedule: Schedule | None = Relationship(
              ~~~~~~~~^~~~~~
TypeError: unsupported operand type(s) for |: 'ForwardRef' and 'NoneType'
```\