streamlit + SQLModel, SQLModel models re-register on Streamlit hot-reload

[bipin-neu]

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

Workarounds Tried

✅ Introduced a shared registry:

if "app.mapper_registry" not in sys.modules:
    mapper_registry = registry()
    sys.modules["foodpal.mapper_registry"] = mapper_registry
else:
    mapper_registry = sys.modules["app.mapper_registry"]


✅ Cleared metadata and class registry on reload:

if "src.core.models" in sys.modules:
    metadata.clear()
    mapper_registry._class_registry.clear()


✅ Ensured consistent imports (single Base, no duplicate import paths).
✅ Used st.cache_resource for connection/provider persistence.

import sys
import os
# --- Ensure single registry across reloads ---
if "app.mapper_registry" not in sys.modules:
    mapper_registry = registry()
    sys.modules["app.mapper_registry"] = mapper_registry
else:
    mapper_registry = sys.modules["app.mapper_registry"]

metadata = mapper_registry.metadata

# --- Guard: clear registry only if model classes already exist ---
# This ensures we only clear if Streamlit *already* imported models before.
if "src.core.models" in sys.modules:
    print("♻️ Streamlit reload detected — clearing stale SQLAlchemy state.")
    try:
        metadata.clear()
        mapper_registry._class_registry.clear()
    except Exception as e:
        print("Warning while clearing registry:", e)

print("=======Registry id:========", id(mapper_registry))

Despite this, the warnings persist because SQLModel still attaches models to its own internal SQLModel.metadata registry.

Description

Environment

Framework: Streamlit (with st.cache_resource)

ORM: SQLModel (built on SQLAlchemy 2.x)

Language: Python 3.13

Context: Running a modularized app using SQLModel models and a custom registry, inside a Streamlit app that uses st.cache_resource to persist an SQLProvider instance.

Problem

Every time Streamlit performs a hot reload (e.g. when code changes or the script re-runs), the SQLModel models are re-imported, causing SQLAlchemy to re-register existing ORM classes on the same DeclarativeBase.

This leads to warnings such as:

SAWarning: This declarative base already contains a class with the same class name and module name as src.core.models.FoodItem, and will be replaced in the string-lookup table.

Even though we manage a shared registry across reloads via sys.modules and clear the metadata/registry on reload, SQLModel still re-adds models to its internal base and triggers these warnings.

Expected Behavior

SQLModel or SQLAlchemy should detect identical re-registrations and skip duplicates on reloads.

Streamlit hot reload should not cause multiple declarative model registrations for the same Base.

Actual Behavior

Each Streamlit reload causes SQLModel’s global declarative base to retain the previous model class definitions.

SQLModel re-registers new class objects with identical names → triggering repeated SAWarning.

This warning repeats for each ORM class on every reload.

In some configurations (without manual registry cleanup), it escalates to a sqlalchemy.exc.InvalidRequestError (“table already defined”).

Operating System

macOS

Operating System Details

M1 Mac
OS: 26.0.1 (25A362)

SQLModel Version

0.0.27

Python Version

Python 3.13.7

Additional Context

No response