Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: gate auth.db and rag.db opens and closes against the SQLite 3.51.0-3.51.1 deadlock (#13307)

Daniel Han40eb194abef9
diff --git a/studio/backend/auth/storage.py b/studio/backend/auth/storage.py
index 4ff3bc00d6f..28eb36822e7 100644
--- a/studio/backend/auth/storage.py
+++ b/studio/backend/auth/storage.py
@@ -19,6 +19,7 @@ from datetime import datetime, timedelta, timezone
import uuid
from typing import Iterator, Optional, Tuple
+from storage import sqlite_gate
from utils.paths import auth_db_path, ensure_dir
DB_PATH = auth_db_path()
@@ -265,7 +266,7 @@ _auth_schema_ready: set[tuple[str, int, int, int]] = set()
def get_connection() -> sqlite3.Connection:
ensure_dir(DB_PATH.parent)
- conn = sqlite3.connect(DB_PATH)
+ conn = sqlite_gate.connect(DB_PATH)
# sqlite3.connect would create the DB 0644 under a 022 umask, exposing identity secrets and password hashes.
for _path, _mode in ((DB_PATH.parent, 0o700), (DB_PATH, 0o600)):
try:
diff --git a/studio/backend/storage/rag_db.py b/studio/backend/storage/rag_db.py
index 1475dfdd177..bcbdec8b89a 100644
--- a/studio/backend/storage/rag_db.py
+++ b/studio/backend/storage/rag_db.py
@@ -22,6 +22,7 @@ from datetime import datetime, timezone
logger = logging.getLogger(__name__)
+from storage import sqlite_gate
from utils.paths import rag_db_path, ensure_dir
# Optional dep: import must never crash this module (imported unconditionally).
@@ -312,7 +313,7 @@ def get_connection() -> sqlite3.Connection:
db_path = rag_db_path()
ensure_dir(db_path.parent)
- conn = sqlite3.connect(str(db_path))
+ conn = sqlite_gate.connect(db_path)
conn.row_factory = sqlite3.Row
# Wait for a lock instead of erroring immediately: a figure-heavy ingest can hold its connection
# across many seconds of vision calls, and a concurrent read would hit "database is locked".
@@ -348,7 +349,7 @@ def get_metadata_connection() -> sqlite3.Connection:
is temporarily unavailable. Callers must not query or mutate the vec0 virtual table."""
db_path = rag_db_path()
ensure_dir(db_path.parent)
- conn = sqlite3.connect(str(db_path))
+ conn = sqlite_gate.connect(db_path)
conn.row_factory = sqlite3.Row
conn.execute("PRAGMA busy_timeout = 5000")
return conn
diff --git a/studio/backend/storage/sqlite_gate.py b/studio/backend/storage/sqlite_gate.py
new file mode 100644
index 00000000000..0c9dc0e5c71
--- /dev/null
+++ b/studio/backend/storage/sqlite_gate.py
@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: AGPL-3.0-only
+# Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+"""One process-wide gate around every Studio SQLite connection open and close.
+
+SQLite 3.51.0-3.51.1 deadlocks when one thread's WAL close (unixIsSharingShmNode) races another
+thread's open or close of the same file: they take the VFS and inode mutexes in opposite order
+(fixed in 3.51.2, #10022). The VFS mutex is process-wide, so one wedged file hangs every database
+(#9008): studio.db, auth.db and rag.db all open through here. Gating only close() still deadlocks.
+"""
+
+from __future__ import annotations
+
+import os
+import sqlite3
+import threading
+from typing import Any
+
+# Reentrant: a GC finalizer can close a pooled connection inside a gated connect on this thread.
+_CONNECTION_GATE = threading.RLock()
+
+
+def _reset_connection_gate_after_fork() -> None:
+ global _CONNECTION_GATE
+ _CONNECTION_GATE = threading.RLock()
+
+
+if hasattr(os, "register_at_fork"):
+ os.register_at_fork(after_in_child = _reset_connection_gate_after_fork)
+
+
+class GatedConnection(sqlite3.Connection):
+ # A connection dropped without close() is finalized natively and bypasses this gate.
+ def close(self) -> None:
+ with _CONNECTION_GATE:
+ super().close()
+
+
+def connect(database: str | os.PathLike[str], **kwargs: Any) -> sqlite3.Connection:
+ """sqlite3.connect with opens and closes serialized process-wide."""
+ with _CONNECTION_GATE:
+ return sqlite3.connect(str(database), factory = GatedConnection, **kwargs)
diff --git a/studio/backend/storage/studio_db.py b/studio/backend/storage/studio_db.py
index edb52eef884..b7c4904fe57 100644
--- a/studio/backend/storage/studio_db.py
+++ b/studio/backend/storage/studio_db.py
@@ -28,6 +28,7 @@ from typing import Any, Callable, Iterable, Iterator, Mapping, Optional
from core import chat_originals
+from storage import sqlite_gate
from utils.account_context import is_owner_context
from utils.paths import (
ensure_account_dir,
@@ -140,33 +141,8 @@ def contains_sensitive_path_component(path: str) -> bool:
_schema_lock = threading.Lock()
_schema_ready: set[Path] = set()
-# SQLite 3.51.0-3.51.1 deadlocks when one thread's WAL close (unixIsSharingShmNode) races another
-# thread's open or close of the same file: they take the VFS and inode mutexes in opposite order
-# (fixed in 3.51.2, #10022). Gating only close() still deadlocks; opens must share the lock.
-# Reentrant: a GC finalizer can close a pooled connection inside a gated connect on this thread.
-_CONNECTION_GATE = threading.RLock()
-
-
-def _reset_connection_gate_after_fork() -> None:
- global _CONNECTION_GATE
- _CONNECTION_GATE = threading.RLock()
-
-
-if hasattr(os, "register_at_fork"):
- os.register_at_fork(after_in_child = _reset_connection_gate_after_fork)
-
-
-class _StudioDbConnection(sqlite3.Connection):
- # A connection dropped without close() is finalized natively and bypasses this gate.
- def close(self) -> None:
- with _CONNECTION_GATE:
- super().close()
-
-
-def connect_studio_db(database: str | os.PathLike[str], **kwargs: Any) -> sqlite3.Connection:
- """sqlite3.connect for studio.db, with opens and closes serialized process-wide."""
- with _CONNECTION_GATE:
- return sqlite3.connect(str(database), factory = _StudioDbConnection, **kwargs)
+# Opens and closes serialized process-wide against the SQLite 3.51.0-3.51.1 deadlock (#10022).
+connect_studio_db = sqlite_gate.connect
_SQLITE_IN_CHUNK_SIZE = 900
diff --git a/studio/backend/tests/test_studio_db_write_lock_contention.py b/studio/backend/tests/test_studio_db_write_lock_contention.py
index 7c4c7a6390e..bea99b57c92 100644
--- a/studio/backend/tests/test_studio_db_write_lock_contention.py
+++ b/studio/backend/tests/test_studio_db_write_lock_contention.py
@@ -193,14 +193,29 @@ def test_concurrent_openers_all_get_normal(db):
def test_studio_db_factories_serialize_connection_close(db, monkeypatch):
- """#10022: every studio.db opener shares one open/close gate (SQLite 3.51.0-3.51.1 deadlock)."""
- from storage import credential_secrets, library_db, mcp_servers_db, providers_db
+ """#10022, #9008: every studio.db, auth.db and rag.db opener shares one open/close gate
+ (SQLite 3.51.0-3.51.1 deadlock wedges the process-wide VFS mutex, so every database hangs)."""
+ import auth.storage as auth_storage
+ from storage import (
+ credential_secrets,
+ library_db,
+ mcp_servers_db,
+ providers_db,
+ rag_db,
+ sqlite_gate,
+ )
modules = (providers_db, mcp_servers_db, credential_secrets, library_db)
for module in modules:
monkeypatch.setattr(module, "studio_db_path", lambda db = db: db)
monkeypatch.setattr(module, "_schema_ready", set())
+ monkeypatch.setattr(auth_storage, "DB_PATH", db.parent / "auth" / "auth.db")
+ monkeypatch.setattr(rag_db, "rag_db_path", lambda: db.parent / "rag.db")
+ monkeypatch.setattr(rag_db, "_schema_ready", set())
factories = [studio_db.get_connection] + [module.get_connection for module in modules]
+ factories += [auth_storage.get_connection, rag_db.get_metadata_connection]
+ if rag_db.rag_available(): # sqlite_vec can import while its vec0 library cannot load
+ factories.append(rag_db.get_connection)
class TrackingLock:
def __init__(self):
@@ -218,7 +233,7 @@ def test_studio_db_factories_serialize_connection_close(db, monkeypatch):
self._lock.release()
gate = TrackingLock()
- monkeypatch.setattr(studio_db, "_CONNECTION_GATE", gate)
+ monkeypatch.setattr(sqlite_gate, "_CONNECTION_GATE", gate)
barrier = threading.Barrier(len(factories))
errors = []
diff --git a/studio/backend/utils/hub_settings.py b/studio/backend/utils/hub_settings.py
index 156c8709c61..ba36c155de5 100644
--- a/studio/backend/utils/hub_settings.py
+++ b/studio/backend/utils/hub_settings.py
@@ -16,7 +16,6 @@ from __future__ import annotations
import json
import os
-import sqlite3
import sys
import threading
import weakref
@@ -26,6 +25,7 @@ from functools import partial
from urllib.parse import urlsplit
from loggers import get_logger
+from storage import sqlite_gate
from utils.hf_endpoint import (
DEFAULTS_BY_HEALTH_KEY,
get_hf_datasets_server,
@@ -93,7 +93,8 @@ def _read_stored() -> dict | None:
path = run_as(OWNER, studio_db_path)
if not path.exists():
return {}
- with closing(sqlite3.connect(f"{path.resolve().as_uri()}?mode=ro", uri = True)) as conn:
+ uri = f"{path.resolve().as_uri()}?mode=ro"
+ with closing(sqlite_gate.connect(uri, uri = True)) as conn:
rows = conn.execute(
"SELECT key, value_json FROM app_settings WHERE key IN (?, ?, ?)", keys
).fetchall()