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.

Drop dead Document.notes legacy column (recovered from #4619) (#4643)

LearningCircuit4c52896cd799
diff --git a/src/local_deep_research/database/migrations/versions/0015_drop_document_notes.py b/src/local_deep_research/database/migrations/versions/0015_drop_document_notes.py
new file mode 100644
index 0000000000..125d113323
--- /dev/null
+++ b/src/local_deep_research/database/migrations/versions/0015_drop_document_notes.py
@@ -0,0 +1,89 @@
+"""Drop dead Document.notes legacy column from the documents table
+
+The ``notes`` column on the ``documents`` table is a dead legacy column.
+It was introduced by the Research Library feature (Issue #207, commit
+3e8cef7cf) and ships to all released users, but it has zero callers in
+``src/`` -- nothing reads from or writes to it. Its name collides
+vocabulary-wise with the separate notes-v2 feature (Document rows with
+``source_type='note'`` plus the ``note_*`` tables), but it is an
+unrelated concept and is safe to remove on its own.
+
+Because the column already exists in every released user's database, it
+cannot be removed as a plain model edit -- it needs a real migration
+that runs on existing ``documents`` tables.
+
+Revision ID: 0015
+Revises: 0014
+Create Date: 2026-06-15
+
+Column Dropped:
+===============
+- notes (TEXT): Unused per-document user notes column. Nullable.
+
+Migration Notes:
+===============
+- Uses SQLite batch mode (table recreation) for ALTER TABLE operations,
+ consistent with the repo's other migrations.
+- Idempotent: skips the drop if the column is already gone (fresh
+ databases created after the model change never had it).
+
+Downgrade Behavior:
+==================
+The downgrade() function re-adds the notes column as a nullable Text
+column. No data is restored (the column carried no data in use).
+"""
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy import inspect
+
+# revision identifiers, used by Alembic.
+revision = "0015"
+down_revision = "0014"
+branch_labels = None
+depends_on = None
+
+
+def column_exists(table_name: str, column_name: str) -> bool:
+ """Check if a column exists in a table."""
+ bind = op.get_bind()
+ inspector = inspect(bind)
+
+ if not inspector.has_table(table_name):
+ return False
+
+ columns = {col["name"] for col in inspector.get_columns(table_name)}
+ return column_name in columns
+
+
+def upgrade():
+ """Drop the dead notes column from documents if it exists."""
+ bind = op.get_bind()
+ inspector = inspect(bind)
+
+ if not inspector.has_table("documents"):
+ # Table doesn't exist yet, will be created by initial migration
+ return
+
+ if not column_exists("documents", "notes"):
+ # Column already gone (fresh database created after model change)
+ return
+
+ # Use batch mode for SQLite compatibility
+ with op.batch_alter_table("documents") as batch_op:
+ batch_op.drop_column("notes")
+
+
+def downgrade():
+ """Re-add the notes column to documents as nullable Text."""
+ bind = op.get_bind()
+ inspector = inspect(bind)
+
+ if not inspector.has_table("documents"):
+ return
+
+ if column_exists("documents", "notes"):
+ return
+
+ with op.batch_alter_table("documents") as batch_op:
+ batch_op.add_column(sa.Column("notes", sa.Text(), nullable=True))
diff --git a/src/local_deep_research/database/models/library.py b/src/local_deep_research/database/models/library.py
index 379523ffc4..500ea3afa9 100644
--- a/src/local_deep_research/database/models/library.py
+++ b/src/local_deep_research/database/models/library.py
@@ -330,7 +330,6 @@ class Document(Base):
# Organization
tags = Column(JSON) # User-defined tags
- notes = Column(Text) # User notes
favorite = Column(Boolean, default=False)
# Timestamps
diff --git a/tests/database/test_migration_0014_benchmark_run_version_and_snapshot.py b/tests/database/test_migration_0014_benchmark_run_version_and_snapshot.py
index f745f6819d..aa2b4d665c 100644
--- a/tests/database/test_migration_0014_benchmark_run_version_and_snapshot.py
+++ b/tests/database/test_migration_0014_benchmark_run_version_and_snapshot.py
@@ -24,7 +24,6 @@ from sqlalchemy import create_engine, inspect, text
from local_deep_research.database.alembic_runner import (
get_alembic_config,
- get_head_revision,
stamp_database,
)
@@ -208,8 +207,3 @@ class TestMigration0014Downgrade:
cols = _columns(engine, "benchmark_runs")
assert "ldr_version" not in cols
assert "settings_snapshot" not in cols
-
-
-class TestMigration0014HeadAlignment:
- def test_head_revision_is_0014(self):
- assert get_head_revision() == "0014"
diff --git a/tests/database/test_migration_0015_drop_document_notes.py b/tests/database/test_migration_0015_drop_document_notes.py
new file mode 100644
index 0000000000..1c08ec6579
--- /dev/null
+++ b/tests/database/test_migration_0015_drop_document_notes.py
@@ -0,0 +1,195 @@
+"""Tests for migration 0015: drop the dead ``documents.notes`` legacy column.
+
+Covers:
+- The drop removes ``notes`` from ``documents``.
+- Other columns, indexes, and row data on the rebuilt table survive.
+- Idempotency (re-run, and tables that never had the column).
+- Missing-table guard.
+- Downgrade re-adds ``notes`` as nullable Text, and a round-trip is stable.
+- Head-alignment: 0015 is the latest revision (the guard lives in the newest
+ migration's test file; 0014 took it from 0013, 0015 takes it from 0014).
+
+Note on test setup
+==================
+Migration 0001 runs ``Base.metadata.create_all()`` against the CURRENT model,
+which (after this PR) no longer has ``notes`` — so a freshly initialised DB
+never has the column. To pin "0015 is the migration that drops it" we use the
+same pattern as ``test_migration_0005_resource_document_id.py`` /
+``test_migration_0014_*``: hand-build a "legacy" ``documents`` table that still
+has ``notes``, stamp at ``0014``, and run the upgrade against that.
+"""
+
+import pytest
+from alembic import command
+from sqlalchemy import create_engine, inspect, text
+
+from local_deep_research.database.alembic_runner import (
+ get_alembic_config,
+ get_head_revision,
+ stamp_database,
+)
+
+
+def _run_upgrade_to(engine, revision):
+ config = get_alembic_config(engine)
+ with engine.begin() as conn:
+ config.attributes["connection"] = conn
+ command.upgrade(config, revision)
+
+
+def _run_downgrade_to(engine, revision):
+ config = get_alembic_config(engine)
+ with engine.begin() as conn:
+ config.attributes["connection"] = conn
+ command.downgrade(config, revision)
+
+
+def _columns(engine, table):
+ insp = inspect(engine)
+ if not insp.has_table(table):
+ return set()
+ return {c["name"] for c in insp.get_columns(table)}
+
+
+def _column_info(engine, table):
+ insp = inspect(engine)
+ if not insp.has_table(table):
+ return {}
+ return {c["name"]: c for c in insp.get_columns(table)}
+
+
+def _index_names(engine, table):
+ insp = inspect(engine)
+ if not insp.has_table(table):
+ return set()
+ return {idx["name"] for idx in insp.get_indexes(table) if idx["name"]}
+
+
+def legacy_engine(tmp_path):
+ """A DB whose ``documents`` table still has the ``notes`` column.
+
+ Simulates an installation created before 0015. Stamped at 0014 so 0015's
+ upgrade is a clean delta. Includes a named index and a seeded row so the
+ batch-mode table rebuild can be checked for column/index/data preservation.
+ """
+ db_path = tmp_path / "legacy_pre_0015.db"
+ engine = create_engine(f"sqlite:///{db_path}")
+
+ with engine.begin() as conn:
+ conn.execute(
+ text(
+ "CREATE TABLE documents ("
+ "id INTEGER PRIMARY KEY AUTOINCREMENT, "
+ "document_hash VARCHAR(64) NOT NULL, "
+ "title VARCHAR(500), "
+ "favorite BOOLEAN NOT NULL DEFAULT 0, "
+ "tags TEXT, "
+ "notes TEXT, "
+ "created_at TEXT NOT NULL"
+ ")"
+ )
+ )
+ conn.execute(
+ text("CREATE INDEX idx_document_hash ON documents (document_hash)")
+ )
+ conn.execute(
+ text(
+ "INSERT INTO documents "
+ "(document_hash, title, favorite, tags, notes, created_at) "
+ "VALUES ('hash-1', 'Doc One', 1, '[\"a\"]', "
+ "'a stray note', '2026-01-01 00:00:00')"
+ )
+ )
+
+ stamp_database(engine, "0014")
+ yield engine
+ engine.dispose()
+
+
+class TestMigration0015Upgrade:
+ def test_drops_notes_column(self, legacy_engine):
+ engine = legacy_engine
+ assert "notes" in _columns(engine, "documents")
+ _run_upgrade_to(engine, "0015")
+ assert "notes" not in _columns(engine, "documents")
+
+ def test_preserves_other_columns(self, legacy_engine):
+ engine = legacy_engine
+ _run_upgrade_to(engine, "0015")
+ cols = _columns(engine, "documents")
+ for expected in {
+ "id",
+ "document_hash",
+ "title",
+ "favorite",
+ "tags",
+ "created_at",
+ }:
+ assert expected in cols
+
+ def test_preserves_index(self, legacy_engine):
+ engine = legacy_engine
+ assert "idx_document_hash" in _index_names(engine, "documents")
+ _run_upgrade_to(engine, "0015")
+ assert "idx_document_hash" in _index_names(engine, "documents")
+
+ def test_preserves_row_data(self, legacy_engine):
+ engine = legacy_engine
+ _run_upgrade_to(engine, "0015")
+ with engine.begin() as conn:
+ row = conn.execute(
+ text(
+ "SELECT document_hash, title, favorite, tags "
+ "FROM documents WHERE document_hash = 'hash-1'"
+ )
+ ).fetchone()
+ assert row is not None
+ assert row[0] == "hash-1"
+ assert row[1] == "Doc One"
+ assert row[2] == 1
+ assert row[3] == '["a"]'
+
+ def test_upgrade_is_idempotent(self, legacy_engine):
+ engine = legacy_engine
+ _run_upgrade_to(engine, "0015")
+ _run_upgrade_to(engine, "0015") # second run is a no-op, no error
+ assert "notes" not in _columns(engine, "documents")
+
+ def test_missing_table_does_not_crash(self, tmp_path):
+ """Upgrade is a no-op when ``documents`` doesn't exist yet."""
+ engine = create_engine(f"sqlite:///{tmp_path}/no_documents.db")
+ stamp_database(engine, "0014")
+ _run_upgrade_to(engine, "0015") # must not raise
+ assert not inspect(engine).has_table("documents")
+ engine.dispose()
+
+
+class TestMigration0015Downgrade:
+ def test_downgrade_readds_notes_nullable(self, legacy_engine):
+ engine = legacy_engine
+ _run_upgrade_to(engine, "0015")
+ assert "notes" not in _columns(engine, "documents")
+ _run_downgrade_to(engine, "0014")
+ cols = _column_info(engine, "documents")
+ assert "notes" in cols
+ assert cols["notes"]["nullable"] is True
+ assert "TEXT" in str(cols["notes"]["type"]).upper()
+
+ def test_downgrade_then_upgrade_roundtrip(self, legacy_engine):
+ engine = legacy_engine
+ _run_upgrade_to(engine, "0015")
+ _run_downgrade_to(engine, "0014")
+ _run_upgrade_to(engine, "0015")
+ assert "notes" not in _columns(engine, "documents")
+ # Seeded row still present after the round-trip.
+ with engine.begin() as conn:
+ count = conn.execute(
+ text("SELECT COUNT(*) FROM documents")
+ ).scalar()
+ assert count == 1
+
+
+class TestMigration0015HeadAlignment:
+ def test_head_revision_is_0015(self):
+ assert get_head_revision() == "0015"