fix(storage): show human-readable error for uninitialized sqlite databases

Author: TryingtobeingNikhil

optuna_dashboard/_storage_url.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import sys
+import optuna
 import os.path
 from pathlib import Path
 import re
@@ -80,7 +82,35 @@ def guess_storage_from_url(storage_url: str) -> BaseStorage:
 
 
 def get_rdb_storage(storage_url: str) -> RDBStorage:
-    return RDBStorage(storage_url, skip_compatibility_check=True, skip_table_creation=True)
+    """Create an RDBStorage instance for the dashboard (read-only viewer).
+
+    Raises SystemExit with a clear message if the database schema has not been
+    initialized (i.e., no Optuna study has ever been run against this storage).
+    """
+    try:
+        return RDBStorage(
+            storage_url,
+            skip_compatibility_check=True,
+            skip_table_creation=True,
+        )
+    except optuna.exceptions.StorageInternalError as e:
+        # This typically happens when the database exists but has no Optuna schema
+        # (e.g., a brand-new empty SQLite file). Provide a human-readable error
+        # instead of a raw SQLAlchemy traceback.
+        err_msg = str(e).lower()
+        cause_msg = str(e.__cause__).lower() if e.__cause__ else ""
+        if "no such table" in err_msg or "version_info" in err_msg or "no such table" in cause_msg or "version_info" in cause_msg:
+            print(
+                f"Error: The database at '{storage_url}' does not contain an Optuna schema.\n"
+                "Please run an Optuna study first to initialize the database:\n\n"
+                "    import optuna\n"
+                "    study = optuna.create_study(storage='<your-storage-url>')\n"
+                "    study.optimize(objective, n_trials=1)\n\n"
+                "Then re-run optuna-dashboard.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        raise  # Re-raise unexpected StorageInternalError variants unchanged
 
 
 def get_journal_file_storage(file_path: str) -> JournalStorage:

python_tests/test_storage_url.py

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
 import tempfile
+import os
+import pytest
 from unittest import TestCase
 import warnings
 
@@ -9,6 +11,7 @@
 from optuna.storages import JournalStorage
 from optuna.storages import RDBStorage
 from optuna_dashboard._storage_url import get_storage
+from optuna_dashboard._storage_url import get_rdb_storage
 import sqlalchemy.exc
 
 
@@ -65,3 +68,13 @@ def test_get_journal_file_storage_invalid(self) -> None:
         with tempfile.NamedTemporaryFile() as file:
             with self.assertRaises(FileNotFoundError):
                 get_storage(f"sqlite:///{file.name}", storage_class="JournalFileStorage")
+
+    def test_get_rdb_storage_empty_db_exits_cleanly(self) -> None:
+        with tempfile.NamedTemporaryFile(suffix=".db", delete=False) as f:
+            empty_db_path = f.name
+        try:
+            with pytest.raises(SystemExit) as exc_info:
+                get_rdb_storage(f"sqlite:///{empty_db_path}")
+            assert exc_info.value.code == 1
+        finally:
+            os.unlink(empty_db_path)