fix(db): isolate SPECIAL_DB_URL from container runtime

SPECIAL_DB_URL was previously loaded via env_file into every container and then silently overridden by the running_in_docker() guard. Moved to a host-shell-only .env.migrations file. Added a warning log in resolve_special_db_runtime_url so any future leak into a container is visible instead of silent.

Author: Francisco

.env.migrations

@@ -0,0 +1,5 @@
+# Host-shell only. Never load this into containers.
+# Use when running alembic migrations from the host:
+#   source .env.migrations && alembic upgrade head
+# (PowerShell: Get-Content .env.migrations | ForEach-Object { ... })
+SPECIAL_DB_URL=mysql+pymysql://api_user:458b6b76b2b70e67357c75ade0ab75d28f00ec5fb9859401fe762421a5881bfc@localhost:3307/entities_db

.gitignore

@@ -10,7 +10,6 @@
 logging_utility = UtilsInterface.LoggingUtility()
 
 # --- ALL ENGINE AND SESSION LOGIC IS NOW CENTRALIZED HERE ---
-
 DATABASE_URL = os.getenv("DATABASE_URL")
 SPECIAL_DB_URL = os.getenv("SPECIAL_DB_URL")
 
@@ -21,7 +20,24 @@ def running_in_docker() -> bool:
 
 
 def resolve_special_db_runtime_url(special_raw: str | None) -> str | None:
+    """
+    Resolve the effective SPECIAL_DB_URL for the current runtime.
+
+    SPECIAL_DB_URL is intended for host-shell use only (see .env.migrations).
+    Its value typically points at localhost:3307, which is meaningless inside
+    containers. If it leaks into container env via .env / env_file, we ignore
+    it and fall back to DATABASE_URL — and log a warning so the leak is
+    visible to the operator.
+    """
     if running_in_docker():
+        if special_raw:
+            logging_utility.warning(
+                "SPECIAL_DB_URL is set inside a container — ignoring and "
+                "falling back to DATABASE_URL. SPECIAL_DB_URL is host-shell-only; "
+                "it should live in .env.migrations, not .env. "
+                "See: https://github.com/project-david-ai/projectdavid-core "
+                "(container hygiene section)."
+            )
         return DATABASE_URL
     return special_raw or None
 
@@ -71,8 +87,6 @@ def get_db():
 
 # Optional: You can also move the wait logic here to keep all DB startup
 # code together, which makes app.py even cleaner.
-
-
 def _wait_for_engine(engine_to_check, db_name, logger, retries=30, delay=3):
     if not engine_to_check:
         return