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

[skyworth-web]

This is expected behavior when using SQLModel together with Streamlit’s hot-reload
mechanism — and it happens because SQLModel maintains its own global declarative base and
global metadata, which are created at import time and are not tied to any custom registry you
create.

Even if you manage your own registry inside sys.modules, SQLModel’s internal base continues to
accumulate model classes on every reload.

---

🔍 Why the SAWarning appears

On every Streamlit reload:

1. The app script is re-executed.
2. Each model class (FoodItem, User, etc.) is redeclared as a new Python class object.
3. SQLModel attaches these new classes to its global DeclarativeBase.
4. SQLAlchemy detects a class with the same name already registered on the same base.
5. It emits:

Clearing your own registry does not help because:

• SQLModel stores its declarative state in SQLModel.metadata
• SQLModel.metadata is a global singleton
• Streamlit reload does not unload SQLModel or reset its internal registry

This leads to the repeated warnings, and in some cases, escalates to:

because SQLModel’s global metadata still contains the table from the first load.

---

❗ Root Cause (important)

SQLModel defines its own declarative system:

class SQLModel(declarative_base()):
    metadata = SQLModelMetadata

[skyworth-web]

The issue happens because SQLModel uses a global declarative base and metadata, and Streamlit
hot-reload re-executes your script without resetting SQLModel’s internal registry. To prevent
duplicate ORM class registrations, there are three working solutions:

1. Cache your model imports with st.cache_resource so SQLModel initializes only once per session.
2. Override SQLModel’s base by creating your own declarative base/metadata and inheriting all
   models from it, so you control the registry instead of the global SQLModel one.
3. Disable Streamlit hot-reload to avoid re-importing models on every code change.

Any of these solutions will stop SQLModel from re-registering models on reload and remove the
warnings.

[chernovssss]

You can try using @st.cache_resource to cache imports. Other imports can be defined as usual. Note, that if you changed something in modules imported this way, changes will not take effect until you restart application.

@st.cache_resource
def get_imports():
    """Cache imports to avoid SQLAlchemy table redefinition errors."""
    from src.database import get_session_context
    from src.product.models import ProductStatus

    return (
        get_session_context,
        ProductStatus,
    )


(
    get_session_context,
    ProductStatus,
) = get_imports()