Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring
TypeScript diagramhomelabhomelab-infrastructure-observabilitynetworkproxmox-veself-hostedzigbeezwavezwave-js
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.pyindex 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, settingslogger = 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.pyindex 7f99a87..a0999e0 100644--- a/backend/tests/conftest.py+++ b/backend/tests/conftest.py@@ -9,7 +9,7 @@ from httpx import ASGITransport, AsyncClientfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_enginefrom 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_dbfrom app.main import appTEST_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 woulddiff --git a/backend/tests/test_documents_migration.py b/backend/tests/test_documents_migration.pyindex 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 == 2await 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()