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(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.md
new file mode 100644
index 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.json
index 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__.py
index 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.py
index 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 MigrationContext
from alembic.script import ScriptDirectory
from loguru import logger
from sqlalchemy import Engine, inspect
+from sqlalchemy.exc import IntegrityError, OperationalError
def 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 engine
revision: 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"
+ )
+ return
logger.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 — with
diff --git a/tests/database/test_alembic_migrations.py b/tests/database/test_alembic_migrations.py
index 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.