Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(database): release pooled connection when outermost session scope ends (#6387)

DustinEwanf760a2e2ba12
diff --git a/src/local_deep_research/database/session_context.py b/src/local_deep_research/database/session_context.py
index 071004a1b9..5e284fa235 100644
--- a/src/local_deep_research/database/session_context.py
+++ b/src/local_deep_research/database/session_context.py
@@ -172,13 +172,14 @@ def get_user_db_session(
f"Could not establish session for {username}"
)
- # Thread-local sessions are managed by the thread — do not close
- # here. But we MUST wrap the yield in try/except so an exception
- # inside the `with` block doesn't leave a half-committed
- # transaction attached to this thread's session. The next caller
- # on the same thread would otherwise inherit that dirty state.
- # Actual connection close happens in `cleanup_current_thread()`,
- # called by middleware / worker-loop finally blocks.
+ # The session is a reused thread-local session. On normal scope exit
+ # (outermost block) the checked-out connection is released in the
+ # ``finally`` below, so the pool isn't pinned for the thread's lifetime.
+ # We MUST wrap the yield in try/except so an exception inside the ``with``
+ # block doesn't leave a half-committed transaction attached to this
+ # thread's session: the next caller on the same thread would otherwise
+ # inherit that dirty state. Thread cleanup (``cleanup_current_thread()``)
+ # remains as a safety net for paths that never exit a scope.
#
# The scope depth tells get_session's re-validation whether an
# enclosing block is still active on this thread: a nested
diff --git a/src/local_deep_research/scheduler/background.py b/src/local_deep_research/scheduler/background.py
index ae7fbeb7af..4bf179817a 100644
--- a/src/local_deep_research/scheduler/background.py
+++ b/src/local_deep_research/scheduler/background.py
@@ -2087,6 +2087,9 @@ class BackgroundJobScheduler:
"model": sub.model,
"search_strategy": sub.search_strategy,
"search_engine": sub.search_engine,
+ # Capture before scope-exit rollback expires the ORM
+ # object, avoiding a lazy refresh while rescheduling.
+ "refresh_interval_minutes": sub.refresh_interval_minutes,
}
logger.info(
@@ -2105,7 +2108,7 @@ class BackgroundJobScheduler:
# For date triggers, reschedule
# Security: random jitter to distribute subscription timing, not security-sensitive
next_run = datetime.now(UTC) + timedelta(
- minutes=sub.refresh_interval_minutes,
+ minutes=subscription_data["refresh_interval_minutes"],
# nosemgrep: semgrep.rules.weak-random-generation, reason: Non-security scheduling or rate-limit jitter
seconds=random.randint(
0, int(self.config.get("max_jitter_seconds", 300))
diff --git a/tests/web/test_user_db_session_release.py b/tests/web/test_user_db_session_release.py
new file mode 100644
index 0000000000..89f4585369
--- /dev/null
+++ b/tests/web/test_user_db_session_release.py
@@ -0,0 +1,167 @@
+"""
+Regression test: get_user_db_session must release its pooled connection when
+the outermost block ends, not hold it for the thread's lifetime.
+
+Before the fix, the thread-local session (and its checked-out QueuePool
+connection) lived until cleanup_current_thread(). M long-lived worker threads
+therefore pinned M connections; once M > pool_size + max_overflow, every new
+block stalled on pool_timeout (the "long periods of inactivity" / QueuePool
+TimeoutError). After the fix, the connection is released at scope end, so the
+checked-out count tracks in-flight blocks, not live threads.
+
+This test FAILS on the buggy code (connections pinned: checkedout == n) and
+PASSES on the fix (connections released: checkedout ~ 0).
+
+Self-contained: imports only session_context + thread_local_session and points
+their db_manager at a real QueuePool SQLite engine (no fastapi/langchain chain).
+"""
+
+import threading
+
+import pytest
+from sqlalchemy import create_engine, text
+from sqlalchemy.orm import sessionmaker
+from sqlalchemy.pool import QueuePool
+
+from local_deep_research.database import session_context, thread_local_session
+
+
+class _FakeDBManager:
+ """Stand-in for encrypted_db.db_manager backed by a real QueuePool engine."""
+
+ def __init__(self, engine):
+ self._engine = engine
+ self._sessionmaker = sessionmaker(bind=engine)
+ self.has_encryption = False
+
+ def open_user_database(self, username, password):
+ return self._engine
+
+ def create_thread_safe_session_for_metrics(self, username, password):
+ return self._sessionmaker()
+
+
+def pooled_engine(monkeypatch):
+ engine = create_engine(
+ "sqlite://",
+ poolclass=QueuePool,
+ pool_size=20,
+ max_overflow=40,
+ pool_timeout=5,
+ # The per-user QueuePool shares connections across worker threads;
+ # default SQLite (check_same_thread=True) would reject that.
+ connect_args={"check_same_thread": False},
+ )
+ with engine.connect() as conn:
+ conn.execute(text("CREATE TABLE IF NOT EXISTS t (id INTEGER)"))
+ conn.commit()
+ fake = _FakeDBManager(engine)
+ manager = thread_local_session.ThreadLocalSessionManager()
+ monkeypatch.setattr(thread_local_session, "thread_session_manager", manager)
+ monkeypatch.setattr(session_context, "thread_session_manager", manager)
+ monkeypatch.setattr(thread_local_session, "db_manager", fake)
+ monkeypatch.setattr(session_context, "db_manager", fake)
+ try:
+ yield engine
+ finally:
+ manager.cleanup_thread()
+ engine.dispose()
+
+
+def test_connection_released_when_block_ends(pooled_engine):
+ engine = pooled_engine
+ username = "alice"
+ n = 15 # worker threads that stay alive after their block
+
+ errors = []
+ barrier = threading.Barrier(n + 1) # n workers + main
+ release = threading.Event()
+
+ def worker():
+ try:
+ with session_context.get_user_db_session(username) as s:
+ s.execute(text("SELECT 1"))
+ except Exception as exc: # noqa: BLE001
+ errors.append(exc)
+ barrier.wait(timeout=20) # every worker finished its `with` block
+ release.wait(timeout=20) # stay alive (pins the session pre-fix)
+
+ threads = [threading.Thread(target=worker, daemon=True) for _ in range(n)]
+ for t in threads:
+ t.start()
+ barrier.wait(
+ timeout=30
+ ) # main is the (n+1)th party; returns when all n done
+ # All n workers have completed their block but are still alive.
+ checked = engine.pool.checkedout()
+ release.set()
+ for t in threads:
+ t.join(timeout=20)
+
+ assert not errors, f"worker errors: {errors}"
+ # Pre-fix: each live thread pins its session -> checkedout == n (15).
+ # Post-fix: connection released at scope end -> checkedout ~ 0.
+ assert checked <= 1, (
+ f"connections still pinned after all blocks ended: checkedout={checked} "
+ f"(expected <= 1). The thread-local session is holding its QueuePool "
+ f"connection for the thread's lifetime instead of releasing it at "
+ f"scope end."
+ )
+
+
+def test_nested_blocks_do_not_close_early(pooled_engine):
+ """A nested get_user_db_session must not release the shared connection
+ while the enclosing block is still active (depth > 0).
+
+ An uncommitted write on the outer session must survive the inner block's
+ exit: if the inner exit had closed the shared connection, the outer
+ session would be detached (or re-acquire a new connection that can't see
+ the uncommitted write), so the SELECT below would fail. A bare
+ ``SELECT 1`` can't establish this — after an accidental ``close()`` it
+ silently acquires another connection and still passes.
+ """
+ engine = pooled_engine
+ username = "alice"
+
+ with session_context.get_user_db_session(username) as outer:
+ # Uncommitted write on the shared session (deliberately not committed).
+ outer.execute(text("INSERT INTO t (id) VALUES (42)"))
+ # Nested block on the same thread reuses the shared session.
+ with session_context.get_user_db_session(username) as inner:
+ inner.execute(text("SELECT 1"))
+ # The outer block is still active: its connection must NOT have been
+ # released by the inner block's exit. The uncommitted write must still
+ # be visible on the SAME connection/transaction (a re-acquired
+ # connection couldn't see it).
+ row = outer.execute(text("SELECT id FROM t WHERE id = 42")).fetchone()
+ assert row is not None, (
+ "uncommitted outer write not visible after inner block exit — the "
+ "shared connection was closed by the nested block's exit, "
+ "detaching the outer session."
+ )
+
+ # After the outermost block ends, the connection is released.
+ assert engine.pool.checkedout() <= 1
+
+
+def test_committed_resource_remains_readable_after_scope_exit(pooled_engine):
+ """Connection release must preserve add_resource's ORM return contract."""
+ from local_deep_research.database.models import Base
+ from local_deep_research.web.services.resource_service import add_resource
+
+ Base.metadata.create_all(pooled_engine)
+ resource = add_resource(
+ research_id="research-1",
+ title="Open-access paper",
+ url="https://example.com/paper.pdf",
+ username="alice",
+ )
+
+ # The helper committed and its outermost scope returned the connection.
+ assert pooled_engine.pool.checkedout() == 0
+ # Production sessions expire on commit. Closing would also detach this
+ # instance, making these real caller reads raise DetachedInstanceError.
+ assert resource.id is not None
+ assert resource.title == "Open-access paper"
+ assert resource.url == "https://example.com/paper.pdf"