~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.
Python academiaanthropicarxivbravedeep-researchencryptionhome-automationhomeserverlocallocal-deep-researchlocal-llmmistralollamaopenaipubmedresearchresearch-toolretrieval-augmented-generationsearxngself-hosted
fix(db): stamp pre-Alembic DBs at 0001 to unblock login (#3747) (#3770)
LearningCircuit7cc08d390923
diff --git a/docs/release_notes/1.6.8.md b/docs/release_notes/1.6.8.mdnew file mode 100644index 0000000000..76fb4475b7--- /dev/null+++ b/docs/release_notes/1.6.8.md@@ -0,0 +1,33 @@+# 1.6.8 — release notes++## Bug fixes++- **(#3747) Restored login for databases created before v1.4.0.**+ Users whose encrypted user database was created before 2026-03-25+ (v1.4.0, when Alembic migrations were introduced) could not log in+ after upgrading: their databases lacked the `alembic_version` row, and+ the migration runner attempted to apply migrations from scratch against+ a legacy column shape. Migration `0007`'s index backfill then failed on+ missing columns (e.g. `settings.category`), leaving the database in a+ corrupted intermediate state.++ This release detects pre-Alembic databases on first launch, stamps them+ at the correct baseline (revision `0001`), and lets the remaining+ migrations apply cleanly. Look for the `BUG-3747:` log line at startup+ to confirm the recovery path engaged.++ Affected users just need to update to `1.6.8` (or `:latest` / `:1.6`)+ and restart — the recovery is automatic on the next launch.++ ### Hardening++ - `stamp_database()` is now race-tolerant: concurrent stampers (e.g. two+ same-user logins arriving simultaneously) no longer trigger+ `OperationalError` / `IntegrityError` on the duplicate+ `alembic_version` insert. The race-tolerance is narrowly scoped to+ `alembic_version`-related errors, so disk-full / corruption / unrelated+ `SQLITE_BUSY` errors continue to propagate.+ - `run_migrations()` refuses to operate on what looks like an auth-DB+ shape (only `users` table, optionally with `alembic_version`) — defense+ in depth against accidentally routing the auth engine through the+ user-DB migration runner.diff --git a/package.json b/package.jsonindex 83aa79d582..2df200aa12 100644--- a/package.json+++ b/package.json@@ -1,6 +1,6 @@{"name": "local-deep-research-web",- "version": "1.6.7",+ "version": "1.6.8","description": "Web frontend for Local Deep Research - AI research assistant","private": true,"type": "module",diff --git a/src/local_deep_research/__version__.py b/src/local_deep_research/__version__.pyindex 64206c43be..2382cc1198 100644--- a/src/local_deep_research/__version__.py+++ b/src/local_deep_research/__version__.py@@ -1 +1 @@-__version__ = "1.6.7"+__version__ = "1.6.8"diff --git a/src/local_deep_research/database/alembic_runner.py b/src/local_deep_research/database/alembic_runner.pyindex 95e01b155a..e8f38d8352 100644--- a/src/local_deep_research/database/alembic_runner.py+++ b/src/local_deep_research/database/alembic_runner.py@@ -17,6 +17,7 @@ from alembic.runtime.migration import MigrationContextfrom alembic.script import ScriptDirectoryfrom loguru import loggerfrom sqlalchemy import Engine, inspect+from sqlalchemy.exc import IntegrityError, OperationalErrordef get_migrations_dir() -> Path:@@ -183,15 +184,41 @@ def stamp_database(engine: Engine, revision: str = "head") -> None:Stamp a database with a revision without running migrations.Used for baselining existing databases.+ Concurrency: If two callers race to stamp a fresh database, one will hit+ "table alembic_version already exists" (OperationalError) or a duplicate+ PK on version_num (IntegrityError). Both outcomes are benign — the DB+ ends up stamped — so we swallow them after verifying the table+row are+ in place. A genuine failure (no row appeared) is re-raised.+Args:engine: SQLAlchemy enginerevision: Revision to stamp (default "head")"""config = get_alembic_config(engine)- with engine.begin() as conn:- config.attributes["connection"] = conn- command.stamp(config, revision)+ try:+ with engine.begin() as conn:+ config.attributes["connection"] = conn+ command.stamp(config, revision)+ except (IntegrityError, OperationalError) as exc:+ # Only swallow errors that look like a benign concurrent-stamp+ # race on the alembic_version table itself. A genuine failure+ # (disk full, SQLITE_BUSY on an unrelated table, corruption,+ # etc.) must propagate so callers see the real error.+ msg = str(exc).lower()+ looks_like_race = (+ "alembic_version" in msg # IntegrityError or table-exists race+ or "already exists" in msg # CREATE TABLE race+ )+ if not looks_like_race or get_current_revision(engine) is None:+ raise+ # Race-loss path: another caller stamped first. Don't claim we+ # stamped it ourselves — log at debug only.+ logger.debug(+ f"stamp_database({revision}) lost race to concurrent caller "+ f"({type(exc).__name__}); database is stamped, continuing"+ )+ returnlogger.info(f"Stamped database at revision: {revision}")@@ -240,6 +267,60 @@ def run_migrations(engine: Engine, target: str = "head") -> None:current = get_current_revision(engine)+ # BUG-3747: Pre-Alembic baseline detection.+ #+ # A database that has schema tables but no alembic_version row was+ # created before commit 4fde036df (v1.4.0, 2026-03-21) via+ # Base.metadata.create_all(). Without stamping, command.upgrade() runs+ # 0001 (no-op for existing tables) followed by 0002+ against a legacy+ # column shape. Migration 0007's index backfill silently fails on+ # missing columns (e.g. settings.category), leaving the DB in a+ # corrupted state. Stamping at "0001" bypasses the broken path.+ if current is None:+ inspector = inspect(engine)+ existing_tables = set(inspector.get_table_names())++ # Defensive guard: refuse what looks like an auth database. The+ # auth DB has its own initialization path (`init_auth_database()`+ # in `auth_db.py`) and contains ONLY the `users` table. Pre-+ # Alembic user DBs ALSO contain `users` (created by the old+ # `Base.metadata.create_all()` path before migration 0001 added+ # the explicit skip), so we cannot just check "users present".+ # Instead we check the auth-DB *shape*: only `users`, optionally+ # alongside `alembic_version`. A real user DB always has 50++ # other tables. If the auth engine is ever accidentally routed+ # through this function, this guard will refuse loudly rather+ # than silently pollute the auth DB with user-DB tables.+ non_metadata_tables = existing_tables - {"alembic_version"}+ if non_metadata_tables == {"users"}:+ raise RuntimeError(+ "Refusing to run migrations on what looks like an auth "+ f"database (only 'users' table present; tables: "+ f"{sorted(existing_tables)}). Auth DB is initialized via "+ "init_auth_database()."+ )++ # User-DB sentinels: both tables date to project inception+ # (2025-06-29) and have never been renamed. We require BOTH —+ # any single one could be present on a partial-init test DB+ # (e.g. one that ran `Setting.__table__.create()` directly)+ # where we'd want 0001's `create_all()` to add the missing+ # tables, not be skipped by stamping. A real pre-Alembic+ # production DB has 60+ tables and definitely has both sentinels.+ PRE_ALEMBIC_SENTINELS = {"settings", "research_history"}+ if PRE_ALEMBIC_SENTINELS.issubset(existing_tables):+ logger.warning(+ "BUG-3747: pre-Alembic database detected "+ f"({len(existing_tables)} tables, no alembic_version). "+ "Stamping at revision 0001 before applying migrations."+ )+ stamp_database(engine, "0001")+ current = get_current_revision(engine)+ logger.info(+ f"BUG-3747: pre-Alembic DB stamped at {current}; "+ "proceeding with upgrade to head"+ )+# Short-circuit when the database is already at head. Calling# command.upgrade() unconditionally opens a write transaction via# engine.begin() even when there is nothing to apply — withdiff --git a/tests/database/test_alembic_migrations.py b/tests/database/test_alembic_migrations.pyindex aeb262e937..6cbdc28c7f 100644--- a/tests/database/test_alembic_migrations.py+++ b/tests/database/test_alembic_migrations.py@@ -4684,6 +4684,229 @@ class TestUpgradeFromBuggyV16xUserDatabase:)+class TestPreAlembicDatabaseHotfix:+ """Regression tests for bug #3747 — pre-Alembic DB login failure.++ Real users whose database was created before v1.4.0 (2026-03-25, when+ Alembic was introduced) have schema tables but no alembic_version row.+ Before this hotfix, run_migrations() called command.upgrade() from+ scratch, exposing legacy column shapes to migration 0007's index+ backfill and `download_tracker` scrub.++ The fixture uses raw-SQL legacy schema (NOT Base.metadata.create_all)+ so it reflects what a real pre-2026-03-21 user database actually looks+ like: `settings` omits the modern `category` column, `download_tracker`+ has the legacy shape without a UNIQUE constraint on `url_hash`, etc.+ """++ @pytest.fixture+ def pre_alembic_engine(self, tmp_path):+ engine = create_engine(f"sqlite:///{tmp_path}/pre_alembic.db")+ with engine.begin() as conn:+ # Legacy `settings` shape (no `category`, no `description`,+ # no `ui_element`, no enum extras — just the bare columns+ # that existed at project inception, 2025-06-29).+ conn.execute(+ text(+ """+ CREATE TABLE settings (+ id INTEGER PRIMARY KEY,+ key VARCHAR(255) NOT NULL UNIQUE,+ value JSON,+ type VARCHAR(50) NOT NULL,+ name VARCHAR(255) NOT NULL,+ visible BOOLEAN DEFAULT 1 NOT NULL,+ editable BOOLEAN DEFAULT 1 NOT NULL,+ created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,+ updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP+ )+ """+ )+ )+ conn.execute(+ text(+ """+ CREATE TABLE research_history (+ id VARCHAR(36) PRIMARY KEY,+ query TEXT NOT NULL,+ mode VARCHAR(50),+ status VARCHAR(50),+ created_at DATETIME+ )+ """+ )+ )+ # Legacy `download_tracker` shape: url_hash without the+ # UNIQUE backing that migration 0007 expects to find. This+ # is the table that the unfixed migration path actually+ # trips over via 0007's index backfill / orphan scrub.+ conn.execute(+ text(+ """+ CREATE TABLE download_tracker (+ id INTEGER PRIMARY KEY,+ url TEXT NOT NULL,+ url_hash VARCHAR(64) NOT NULL,+ first_resource_id INTEGER,+ is_downloaded BOOLEAN DEFAULT 0+ )+ """+ )+ )+ # Sanity: fixture really is pre-Alembic-shaped.+ inspector = inspect(engine)+ assert "alembic_version" not in inspector.get_table_names()+ assert "category" not in {+ c["name"] for c in inspector.get_columns("settings")+ }+ yield engine+ engine.dispose()++ def test_pre_alembic_db_reaches_head_and_stamp_branch_engaged(+ self, pre_alembic_engine, loguru_caplog+ ):+ """Core regression: pre-Alembic DB → run_migrations() → head, AND+ the BUG-3747 stamp branch is what got it there (not a coincidence)."""+ with loguru_caplog.at_level("WARNING"):+ run_migrations(pre_alembic_engine)+ assert get_current_revision(pre_alembic_engine) == get_head_revision()+ assert (+ "alembic_version" in inspect(pre_alembic_engine).get_table_names()+ )+ # Without the hotfix this log line never appears — its presence+ # proves we got to head via the stamp path, not by accident.+ assert "BUG-3747: pre-Alembic database detected" in loguru_caplog.text++ def test_pre_alembic_migration_is_idempotent(self, pre_alembic_engine):+ """Re-running run_migrations() after the hotfix is a no-op."""+ run_migrations(pre_alembic_engine)+ rev1 = get_current_revision(pre_alembic_engine)+ run_migrations(pre_alembic_engine)+ assert get_current_revision(pre_alembic_engine) == rev1++ def test_fresh_db_does_not_enter_stamp_branch(+ self, tmp_path, loguru_caplog+ ):+ """An empty DB must run upgrade from 0001, not the stamp branch."""+ engine = create_engine(f"sqlite:///{tmp_path}/fresh.db")+ try:+ with loguru_caplog.at_level("WARNING"):+ run_migrations(engine)+ assert get_current_revision(engine) == get_head_revision()+ assert "BUG-3747" not in loguru_caplog.text+ finally:+ engine.dispose()++ def test_concurrent_stamp_is_neutralized(self, pre_alembic_engine):+ """stamp_database() must be safe to call twice (race-tolerant)."""+ stamp_database(pre_alembic_engine, "0001")+ # Second call simulates a racing concurrent caller — must NOT raise.+ stamp_database(pre_alembic_engine, "0001")+ assert get_current_revision(pre_alembic_engine) == "0001"++ def test_unrelated_operational_error_still_propagates(self, tmp_path):+ """The race-tolerance guard must NOT swallow non-race errors."""+ from alembic import command+ from sqlalchemy.exc import OperationalError++ engine = create_engine(f"sqlite:///{tmp_path}/will_error.db")+ original_stamp = command.stamp++ def _raise_unrelated(*_args, **_kwargs):+ raise OperationalError(+ "SELECT something", {}, Exception("disk I/O error")+ )++ try:+ command.stamp = _raise_unrelated+ with pytest.raises(OperationalError, match="disk I/O error"):+ stamp_database(engine, "0001")+ finally:+ command.stamp = original_stamp+ engine.dispose()++ def test_auth_db_shape_users_only_is_refused(self, tmp_path):+ """Engine with ONLY a `users` table must be refused (auth DB shape)."""+ engine = create_engine(f"sqlite:///{tmp_path}/auth.db")+ try:+ with engine.begin() as conn:+ conn.execute(+ text(+ "CREATE TABLE users "+ "(id INTEGER PRIMARY KEY, username VARCHAR)"+ )+ )+ with pytest.raises(RuntimeError, match="auth database"):+ run_migrations(engine)+ finally:+ engine.dispose()++ def test_auth_db_shape_users_plus_alembic_version_is_refused(+ self, tmp_path+ ):+ """Auth DB that's been (mis-)stamped must still be refused."""+ engine = create_engine(f"sqlite:///{tmp_path}/auth_stamped.db")+ try:+ with engine.begin() as conn:+ conn.execute(+ text(+ "CREATE TABLE users "+ "(id INTEGER PRIMARY KEY, username VARCHAR)"+ )+ )+ conn.execute(+ text(+ "CREATE TABLE alembic_version "+ "(version_num VARCHAR(32) NOT NULL PRIMARY KEY)"+ )+ )+ with pytest.raises(RuntimeError, match="auth database"):+ run_migrations(engine)+ finally:+ engine.dispose()++ def test_pre_alembic_user_db_with_users_table_is_NOT_refused(+ self, tmp_path+ ):+ """Pre-Alembic user DBs contain `users` (created by the old+ `Base.metadata.create_all()` path before migration 0001 added+ the explicit skip). They must be allowed through, not refused+ as auth DBs.++ Uses `Base.metadata.create_all()` to simulate the legacy code+ path exactly — same approach as the existing pre-Alembic tests+ (see `test_pre_alembic_db_with_users_table_keeps_it`).+ """+ engine = create_engine(f"sqlite:///{tmp_path}/pre_alembic_user.db")+ try:+ Base.metadata.create_all(engine, checkfirst=True)+ # Sanity: the simulated pre-Alembic DB really does contain+ # `users` (the modern 0001 migration would have skipped it).+ assert "users" in inspect(engine).get_table_names()+ # Must NOT raise as an auth-DB false positive.+ run_migrations(engine)+ assert get_current_revision(engine) == get_head_revision()+ finally:+ engine.dispose()++ def test_only_alembic_version_table_is_treated_as_fresh(self, tmp_path):+ """A bare alembic_version (no schema, no users) is OK — runs upgrade."""+ engine = create_engine(f"sqlite:///{tmp_path}/bare.db")+ try:+ with engine.begin() as conn:+ conn.execute(+ text(+ "CREATE TABLE alembic_version "+ "(version_num VARCHAR(32) NOT NULL "+ "PRIMARY KEY)"+ )+ )+ run_migrations(engine)+ assert get_current_revision(engine) == get_head_revision()+ finally:+ engine.dispose()++class TestMigrationAppliesSchemaChanges:"""Tests proving the migration machinery actually changes schema and ORM works.