Support SQLModel UTC datetime migrations without downgrades (#7462)

* Support SQLModel UTC datetime migrations without downgrades

* Address SQLModel compatibility review feedback

Author: masenf

docs/database/tables.md

@@ -32,6 +32,43 @@ It is not currently possible to create a table without a primary key.
 
 ## Advanced Column Types
 
+### Datetimes and SQLModel upgrades
+
+From SQLModel 0.0.45, a plain `datetime` field uses `UTCDateTime`:
+database writes require timezone-aware values, and reads return UTC-aware values,
+including on SQLite. Migrations generated with these versions reference
+`sqlmodel.sql.sqltypes.UTCDateTime()` and require SQLModel 0.0.45 or later when
+they run. Keep the SQLModel version used to generate migrations in your deployment
+dependencies; for example, `sqlmodel>=0.0.45` if a migration uses `UTCDateTime`.
+
+For existing apps that store naive datetimes, declare the SQLAlchemy type
+explicitly to preserve that behavior across SQLModel versions:
+
+```python
+from datetime import datetime
+
+from sqlalchemy import DateTime
+from sqlmodel import Field
+
+
+class Post(rx.Model, table=True):
+    created_at: datetime = Field(
+        default_factory=datetime.now,
+        sa_type=DateTime(timezone=False),
+    )
+```
+
+On SQLModel 0.0.45 or later, Pydantic's `NaiveDatetime` annotation also selects
+naive storage. For UTC storage, use aware producers such as
+`datetime.now(timezone.utc)`, and update comparisons, query parameters, and
+database defaults to use aware values. Changing the Python field type does not
+convert existing database values: determine the timezone of stored data and
+apply a database-specific migration before adopting UTC storage. Follow
+[SQLModel's datetime upgrade guide](https://sqlmodel.tiangolo.com/advanced/datetime/#upgrade-existing-applications)
+for the PostgreSQL, SQLite, and MySQL migration details.
+
+### Explicit column types
+
 SQLModel automatically maps basic python types to SQLAlchemy column types, but
 for more advanced use cases, it is possible to define the column type using
 `sqlalchemy` directly. For example, we can add a last updated timestamp to the

news/+refresh-dependencies.misc.md

@@ -1 +1 @@
-Allow wrapt 2.4 and 2.5, and keep SQLModel below 0.0.45 to preserve existing datetime storage behavior.
+Allow wrapt 2.4 and 2.5.

pyproject.toml

@@ -63,8 +63,7 @@ classifiers = [
 db = [
   "alembic >=1.15.2,<2.0",
   "pydantic >=2.12.0,<3.0",
-  # 0.0.45 changes datetime columns to UTC and rejects existing naive values.
-  "sqlmodel >=0.0.24,<0.0.45",
+  "sqlmodel >=0.0.24",
 ]
 pydantic = ["reflex-base[pydantic]"]
 testing = [
@@ -487,9 +486,6 @@ backend_held = [
     # (including `get_state`, so it is not test-only). See #7026 for the reproduction
     # and the A/B that isolated it; requested in #6764.
     "redis",
-    # 0.0.45 changes datetime storage and requires existing database migrations.
-    # Keep naive datetime defaults working until a compatibility path is available.
-    "sqlmodel",
 ]
 backend_pinned = [
     # Linters are pinned deliberately and bumped on their own cadence.

tests/units/test_check_outdated_deps.py

@@ -173,3 +173,28 @@ def test_load_config_reads_the_repo_config():
     # and the hold is policy, not a blocker.
     assert "ruff" in check_outdated_deps._load_config("backend")[1]
     assert "ag-grid*" in check_outdated_deps._load_config("frontend")[1]
+
+
+@pytest.mark.parametrize("sqlmodel_outdated", [False, True])
+def test_sqlmodel_updates_are_reported(sqlmodel_outdated: bool):
+    """SQLModel stays visible to the checker without a stale hold at latest.
+
+    Args:
+        sqlmodel_outdated: Whether SQLModel has an available update.
+    """
+    held, pinned = check_outdated_deps._load_config("backend")
+    other_held = [
+        package
+        for package in held
+        if not check_outdated_deps.matches(package, "sqlmodel")
+    ]
+    outdated = ["sqlmodel"] if sqlmodel_outdated else []
+    reportable, suppressed, stale = check_outdated_deps.partition(
+        outdated=[*other_held, *outdated],
+        installed=[*other_held, "sqlmodel"],
+        held=held,
+        pinned=pinned,
+    )
+    assert reportable == outdated
+    assert suppressed == other_held
+    assert stale == []

tests/units/test_model.py

@@ -1,8 +1,11 @@
+import datetime
 import math
+import tomllib
 from pathlib import Path
 from unittest import mock
 
 import pytest
+from packaging.requirements import Requirement
 from reflex_base.constants.state import FIELD_MARKER
 from reflex_base.event import Event
 
@@ -23,8 +26,74 @@
 )
 
 pytest.importorskip("alembic")
-pytest.importorskip("sqlalchemy")
-pytest.importorskip("sqlmodel")
+sa = pytest.importorskip("sqlalchemy")
+sqlmodel = pytest.importorskip("sqlmodel")
+
+
+@pytest.mark.parametrize("version", ["0.0.45", "0.0.47"])
+def test_db_extra_accepts_utc_sqlmodel(version: str):
+    """The database extra must accept versions used to generate UTC migrations.
+
+    Args:
+        version: A SQLModel version supporting UTCDateTime.
+    """
+    project = tomllib.loads((Path(__file__).parents[2] / "pyproject.toml").read_text())
+    requirement = next(
+        parsed
+        for dep in project["project"]["optional-dependencies"]["db"]
+        if (parsed := Requirement(dep)).name == "sqlmodel"
+    )
+    assert requirement.specifier.contains(version)
+
+
+@pytest.mark.skipif(
+    not hasattr(sqlmodel, "UTCDateTime"), reason="SQLModel before 0.0.45"
+)
+def test_utc_datetime_migration_and_roundtrip(
+    tmp_working_dir: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    model_registry: type[ModelRegistry],
+):
+    """Generated UTC migrations work on fresh databases and retain aware datetimes.
+
+    Args:
+        tmp_working_dir: The database and migration directory.
+        monkeypatch: The configuration patch fixture.
+        model_registry: The isolated model registry.
+    """
+    monkeypatch.setattr(
+        reflex.constants, "ALEMBIC_CONFIG", str(tmp_working_dir / "alembic.ini")
+    )
+    config = mock.Mock(db_url=f"sqlite:///{tmp_working_dir}/reflex.db")
+    monkeypatch.setattr(reflex.model, "get_config", lambda: config)
+    alembic_init()
+
+    class UTCPost(Model, table=True):
+        created_at: datetime.datetime
+
+    with get_engine().connect() as connection:
+        assert alembic_autogenerate(connection=connection, message="UTC datetime")
+    migration = next((tmp_working_dir / "alembic" / "versions").glob("*.py"))
+    assert "sqlmodel.sql.sqltypes.UTCDateTime()" in migration.read_text()
+    assert migrate()
+
+    value = datetime.datetime(
+        2026, 9, 21, 12, tzinfo=datetime.timezone(datetime.timedelta(hours=5))
+    )
+    with reflex.model.session() as session:
+        session.add(UTCPost(created_at=value))
+        session.commit()
+        stored = session.exec(sqlmodel.select(UTCPost)).one()
+        assert stored.created_at == value
+        assert stored.created_at.utcoffset() == datetime.timedelta(0)
+
+    get_engine().dispose()
+    (tmp_working_dir / "reflex.db").unlink()
+    assert migrate()
+    with reflex.model.session() as session:
+        assert session.exec(sqlmodel.select(UTCPost)).all() == []
+
+    model_registry.get_metadata().clear()
 
 
 @pytest.fixture
@@ -115,6 +184,10 @@ class AlembicThing(Model, table=True):  # pyright: ignore [reportRedeclaration]
     version_scripts = list(versions.glob("*.py"))
     assert len(version_scripts) == 1
     assert version_scripts[0].name.endswith("initial_revision.py")
+    assert set(sa.inspect(get_engine()).get_table_names()) == {
+        "alembic_version",
+        "alembicthing",
+    }
 
     with reflex.model.session() as session:
         session.add(AlembicThing(id=None, t1="foo"))
@@ -263,7 +336,8 @@ class AlembicCallable(Model, table=True):  # pyright: ignore [reportRedeclaratio
     class AlembicCallable(Model, table=True):  # pyright: ignore [reportRedeclaration]
         t1: str
         created: datetime.datetime = sqlmodel.Field(
-            default_factory=datetime.datetime.now
+            default_factory=datetime.datetime.now,
+            sa_type=sa.DateTime(timezone=False),
         )
         count: int = 5
 
@@ -290,7 +364,8 @@ class AlembicCallable(Model, table=True):  # pyright: ignore [reportRedeclaratio
     class AlembicCallable(Model, table=True):  # pyright: ignore [reportRedeclaration]
         t1: str
         created: datetime.datetime = sqlmodel.Field(
-            default_factory=datetime.datetime.now
+            default_factory=datetime.datetime.now,
+            sa_type=sa.DateTime(timezone=False),
         )
         count: int = 5
         note: str | None = sqlmodel.Field(default_factory=lambda: "generated")