Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

fix(docs): bring an existing documents table up to the current shape

Pouzord52f698de3c0
diff --git a/backend/app/db/database.py b/backend/app/db/database.py
index 00e9184..2e60630 100644
--- a/backend/app/db/database.py
+++ b/backend/app/db/database.py
@@ -17,10 +17,35 @@ from app.core.config import APP_VERSION, settings
logger = logging.getLogger(__name__)
-# DDL for the documents feature that `Base.metadata.create_all` cannot express:
-# a virtual table, and partial indexes. Shared with the test fixtures so the
-# suite runs against the same schema production boots with.
+# DDL for the documents feature that `Base.metadata.create_all` does not apply:
+# the column additions it never makes to an existing table, plus a virtual table
+# and partial indexes it cannot express at all. Shared with the test fixtures so
+# the suite runs against the same schema production boots with.
DOCUMENT_DDL: tuple[tuple[str, str], ...] = (
+ # `create_all` creates a missing table; it never adds a column to one that
+ # already exists. A database that met an earlier shape of `documents` — an
+ # intermediate build, a branch checked out and run before a column landed —
+ # keeps that shape forever, and every query naming the new column fails with
+ # `no such column`. So every nullable / defaulted column is (re)stated here
+ # as an idempotent ALTER, the way the `device_inventory` migrations are.
+ ("documents.icon", "ALTER TABLE documents ADD COLUMN icon TEXT"),
+ ("documents.parent_id", "ALTER TABLE documents ADD COLUMN parent_id TEXT"),
+ ("documents.sort_order", "ALTER TABLE documents ADD COLUMN sort_order INTEGER DEFAULT 0"),
+ ("documents.device_id", "ALTER TABLE documents ADD COLUMN device_id TEXT"),
+ ("documents.node_id", "ALTER TABLE documents ADD COLUMN node_id TEXT"),
+ ("documents.design_id", "ALTER TABLE documents ADD COLUMN design_id TEXT"),
+ ("documents.frontmatter", "ALTER TABLE documents ADD COLUMN frontmatter JSON"),
+ ("documents.tags", "ALTER TABLE documents ADD COLUMN tags JSON"),
+ ("documents.starred", "ALTER TABLE documents ADD COLUMN starred BOOLEAN DEFAULT 0"),
+ ("documents.template_id", "ALTER TABLE documents ADD COLUMN template_id TEXT"),
+ ("documents.facts_snapshot", "ALTER TABLE documents ADD COLUMN facts_snapshot JSON"),
+ ("documents.facts_synced_at", "ALTER TABLE documents ADD COLUMN facts_synced_at DATETIME"),
+ ("documents.reviewed_at", "ALTER TABLE documents ADD COLUMN reviewed_at DATETIME"),
+ # Set only when a body is edited, so "never touched since it was generated"
+ # is distinguishable from "edited" — `created_at` and `updated_at` are two
+ # separate clock reads on insert and are never equal.
+ ("documents.edited_at", "ALTER TABLE documents ADD COLUMN edited_at DATETIME"),
+ ("document_revisions.reason", "ALTER TABLE document_revisions ADD COLUMN reason TEXT"),
(
"documents_fts.table",
"CREATE VIRTUAL TABLE IF NOT EXISTS documents_fts USING fts5("
@@ -555,9 +580,10 @@ async def init_db() -> None:
):
await _try_migrate(conn, sql, label=label)
- # Documents. The two tables come from create_all; only what create_all
- # cannot express lives here — the FTS5 index and the partial uniques
- # that keep one document per device / node / design.
+ # Documents. create_all makes the two tables on a fresh database; this
+ # brings an existing one up to the current shape — the columns create_all
+ # would never add, the FTS5 index and the partial uniques that keep one
+ # document per device / node / design.
for label, sql in DOCUMENT_DDL:
await _try_migrate(conn, sql, label=label)
diff --git a/backend/tests/conftest.py b/backend/tests/conftest.py
index 7f99a87..a0999e0 100644
--- a/backend/tests/conftest.py
+++ b/backend/tests/conftest.py
@@ -9,7 +9,7 @@ from httpx import ASGITransport, AsyncClient
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
from app.core.security import hash_password
-from app.db.database import DOCUMENT_DDL, Base, get_db
+from app.db.database import DOCUMENT_DDL, Base, _try_migrate, get_db
from app.main import app
TEST_DB_URL = "sqlite+aiosqlite:///:memory:"
@@ -28,10 +28,12 @@ async def db_session():
engine = create_async_engine(TEST_DB_URL)
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
- # create_all cannot express the documents FTS5 table or its partial
- # uniques; apply the same DDL init_db does so the suite matches boot.
- for _label, sql in DOCUMENT_DDL:
- await conn.exec_driver_sql(sql)
+ # Apply the same documents DDL init_db does, through the same helper, so
+ # the suite matches boot. `_try_migrate` matters here: on a database
+ # create_all has just built, every ALTER in that list is a no-op that
+ # raises "duplicate column" — swallowing it is the point, not a leniency.
+ for label, sql in DOCUMENT_DDL:
+ await _try_migrate(conn, sql, label=label)
session_factory = async_sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
# Background tasks open their own session through `AsyncSessionLocal` — the
# request-scoped `get_db` override does not reach them. Left alone they would
diff --git a/backend/tests/test_documents_migration.py b/backend/tests/test_documents_migration.py
index c8d9f78..514d1ad 100644
--- a/backend/tests/test_documents_migration.py
+++ b/backend/tests/test_documents_migration.py
@@ -1,8 +1,10 @@
-"""The documents DDL `create_all` cannot express.
+"""The documents DDL `create_all` does not apply.
-A virtual table and three partial indexes, applied through `_try_migrate` at
-boot. Both have to survive a second boot untouched, and the partial uniques are
-what stop two documents claiming the same device behind the route's own check.
+Column additions to an existing table (which `create_all` never makes), plus a
+virtual table and three partial indexes (which it cannot express at all), all
+applied through `_try_migrate` at boot. Every one has to survive a second boot
+untouched, and the partial uniques are what stop two documents claiming the same
+device behind the route's own check.
"""
import pytest
@@ -82,3 +84,75 @@ async def test_many_documents_may_have_no_device(tmp_path):
count = (await conn.exec_driver_sql("SELECT COUNT(*) FROM documents")).scalar_one()
assert count == 2
await engine.dispose()
+
+
+# ── columns added to a table that already exists ─────────────────────────────
+
+# `documents` as an earlier build of the feature created it: no `edited_at`.
+_DOCUMENTS_WITHOUT_EDITED_AT = (
+ "CREATE TABLE documents ("
+ "id VARCHAR NOT NULL PRIMARY KEY, kind VARCHAR NOT NULL, title VARCHAR NOT NULL, "
+ "slug VARCHAR NOT NULL, icon VARCHAR, parent_id VARCHAR, sort_order INTEGER, "
+ "device_id VARCHAR, node_id VARCHAR, design_id VARCHAR, body TEXT NOT NULL, "
+ "frontmatter JSON, tags JSON, starred BOOLEAN, template_id VARCHAR, "
+ "facts_snapshot JSON, facts_synced_at DATETIME, reviewed_at DATETIME, "
+ "created_at DATETIME, updated_at DATETIME)"
+)
+
+
+async def _columns(engine, table: str) -> list[str]:
+ async with engine.begin() as conn:
+ rows = (await conn.exec_driver_sql(f"PRAGMA table_info({table})")).fetchall()
+ return [row[1] for row in rows]
+
+
+async def test_an_existing_table_gains_the_columns_create_all_would_not_add(tmp_path):
+ """The regression: `create_all` makes a missing table, never a missing column.
+
+ A database that met an earlier shape of `documents` kept it, and every query
+ naming `edited_at` failed with ``no such column: documents.edited_at`` —
+ including the one behind opening the Documentation section.
+ """
+ engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path / 'test.db'}")
+ async with engine.begin() as conn:
+ await conn.exec_driver_sql(_DOCUMENTS_WITHOUT_EDITED_AT)
+ assert "edited_at" not in await _columns(engine, "documents")
+
+ async with engine.begin() as conn:
+ await conn.run_sync(Base.metadata.create_all) # sees the table, leaves it be
+ for label, sql in DOCUMENT_DDL:
+ await _try_migrate(conn, sql, label=label)
+
+ assert "edited_at" in await _columns(engine, "documents")
+ await engine.dispose()
+
+
+async def test_the_old_rows_survive_the_column_being_added(tmp_path):
+ engine = create_async_engine(f"sqlite+aiosqlite:///{tmp_path / 'test.db'}")
+ async with engine.begin() as conn:
+ await conn.exec_driver_sql(_DOCUMENTS_WITHOUT_EDITED_AT)
+ await conn.exec_driver_sql(
+ "INSERT INTO documents (id, kind, title, slug, body) "
+ "VALUES ('d1', 'page', 'Rebuild plan', 'rebuild-plan', '# Rebuild plan')"
+ )
+
+ async with engine.begin() as conn:
+ await conn.run_sync(Base.metadata.create_all)
+ for label, sql in DOCUMENT_DDL:
+ await _try_migrate(conn, sql, label=label)
+
+ async with engine.begin() as conn:
+ row = (
+ await conn.exec_driver_sql("SELECT title, body, edited_at FROM documents WHERE id = 'd1'")
+ ).fetchone()
+ assert row == ("Rebuild plan", "# Rebuild plan", None)
+ await engine.dispose()
+
+
+async def test_a_fresh_database_has_every_column(tmp_path):
+ engine = await _boot(tmp_path, times=2)
+ columns = await _columns(engine, "documents")
+ assert "edited_at" in columns
+ # The re-stated ALTERs are idempotent: no column is added twice.
+ assert len(columns) == len(set(columns))
+ await engine.dispose()