show errors on multiple instances or missing init (#1151)

Author: davidism

CHANGES.rst

@@ -3,6 +3,9 @@ Version 3.0.3
 
 Unreleased
 
+-   Show helpful errors when mistakenly using multiple ``SQLAlchemy`` instances for the
+    same app, or without calling ``init_app``. :pr:`1151`
+
 
 Version 3.0.2
 -------------

src/flask_sqlalchemy/extension.py

@@ -249,6 +249,12 @@ def init_app(self, app: Flask) -> None:
 
         :param app: The Flask application to initialize.
         """
+        if "sqlalchemy" in app.extensions:
+            raise RuntimeError(
+                "A 'SQLAlchemy' instance has already been registered on this Flask app."
+                " Import and use that instance instead."
+            )
+
         app.extensions["sqlalchemy"] = self
 
         if self._add_models_to_shell:
@@ -626,6 +632,14 @@ def engines(self) -> t.Mapping[str | None, sa.engine.Engine]:
         .. versionadded:: 3.0
         """
         app = current_app._get_current_object()  # type: ignore[attr-defined]
+
+        if app not in self._app_engines:
+            raise RuntimeError(
+                "The current Flask app is not registered with this 'SQLAlchemy'"
+                " instance. Did you forget to call 'init_app', or did you create"
+                " multiple 'SQLAlchemy' instances?"
+            )
+
         return self._app_engines[app]
 
     @property

tests/test_metadata.py

@@ -116,6 +116,7 @@ def test_reflect(app: Flask) -> None:
     db.Table("post", sa.Column("id", sa.Integer, primary_key=True), bind_key="post")
     db.create_all()
 
+    del app.extensions["sqlalchemy"]
     db = SQLAlchemy(app)
     assert not db.metadata.tables
     db.reflect()