Merge pull request #24 from codebude/feature/docs-content-update

feature/docs content update

Author: codebude

backend/app/services/backup_restore.py

@@ -26,10 +26,77 @@
 _LOCK_FILE: str = "backup_restore.lock"
 
 
+def _remove_wal_files(db_path: str) -> None:
+    """Remove stale WAL and SHM files left by a WAL-mode database.
+
+    Must be called after replacing the database file on disk and before
+    opening any new connection, otherwise SQLite will try to replay the old
+    WAL into the new database — causing B‑tree corruption.
+    """
+    for suffix in ("-wal", "-shm"):
+        path = f"{db_path}{suffix}"
+        if os.path.isfile(path):
+            os.remove(path)
+
+
+def _run_alembic_migrations() -> None:
+    """Run all pending alembic migrations to bring the database schema up to date.
+
+    This is necessary when restoring a backup from an older release whose schema
+    may be behind the current codebase.
+    """
+    from alembic.config import Config
+    from alembic.command import upgrade
+
+    alembic_cfg = Config(os.path.join(os.path.dirname(__file__), "..", "..", "alembic.ini"))
+    upgrade(alembic_cfg, "head")
+
+
+def _stamp_alembic_head_if_fresh() -> None:
+    """Stamp alembic_version at the current head when the version table is absent
+    or empty.
+
+    After ``SQLModel.metadata.create_all()`` creates tables directly (bypassing
+    alembic), alembic would otherwise try to re-run the initial migration and fail
+    with *table already exists*.
+
+    When ``alembic_version`` already has a row (e.g. an old backup was restored),
+    stamping is skipped so that ``alembic upgrade head`` can apply pending
+    migrations on top of whatever revision the backup was at.
+    """
+    from alembic.config import Config
+    from alembic import command
+    from alembic.script import ScriptDirectory
+
+    import sqlite3
+
+    db_path = _extract_db_path(settings.database_url)
+    conn = sqlite3.connect(db_path)
+    try:
+        cursor = conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name='alembic_version'"
+        )
+        table_exists = cursor.fetchone() is not None
+        if table_exists:
+            row_count = conn.execute("SELECT COUNT(*) FROM alembic_version").fetchone()[0]
+            if row_count > 0:
+                return
+    finally:
+        conn.close()
+
+    alembic_cfg = Config(os.path.join(os.path.dirname(__file__), "..", "..", "alembic.ini"))
+    script = ScriptDirectory.from_config(alembic_cfg)
+    head = script.get_current_head()
+    if head:
+        command.stamp(alembic_cfg, head)
+
+
 def _recreate_engine() -> None:
     """Replace the global SQLAlchemy engine with a fresh one.
 
     Called after restoring the database on disk so the app picks up the new data.
+    Also runs pending alembic migrations for backward compatibility with backups
+    created by older releases.
     """
     from app.database import create_engine as _create_engine
     from sqlmodel import SQLModel
@@ -39,6 +106,8 @@ def _recreate_engine() -> None:
         connect_args={"check_same_thread": False},
     )
     SQLModel.metadata.create_all(new_engine)
+    _stamp_alembic_head_if_fresh()
+    _run_alembic_migrations()
     db_mod.engine = new_engine
 
 
@@ -272,6 +341,7 @@ def _rollback_safety_backup(safety_dir: str, database_url: str, data_dir: str) -
     safety_db = os.path.join(safety_dir, "database.db")
     if os.path.isfile(safety_db):
         shutil.copy2(safety_db, db_path)
+        _remove_wal_files(db_path)
     for item_name in os.listdir(safety_dir):
         if item_name == "database.db":
             continue
@@ -368,6 +438,8 @@ def restore_backup(
                     os.remove(tmp_path)
                 raise
 
+            _remove_wal_files(db_path)
+
             tmp_db_path = _extract_db_path(database_url)
             # NOTE: sqlite3.connect() context manager manages transactions, NOT
             # the connection itself. See note in _vacuum_into_backup above.

backend/tests/test_backup_restore.py

@@ -546,14 +546,13 @@ def test_restore_backup_single_file_too_large(valid_backup_zip: bytes, tmp_db_pa
 
 # ── _recreate_engine ──────────────────────────────────────────────────────────
 
-def test_recreate_engine(monkeypatch: MonkeyPatch) -> None:
+def test_recreate_engine(monkeypatch: MonkeyPatch, tmp_path: Path) -> None:
     """_recreate_engine should replace app.database.engine."""
     import app.database as db_mod
 
     original_engine = db_mod.engine
+    tmp_db = str(tmp_path / "test.db")
     try:
-        # Use a temp DB path
-        tmp_db = "/tmp/test_recreate_engine.db"
         conn = sqlite3.connect(tmp_db)
         conn.execute("CREATE TABLE IF NOT EXISTS t (id INT)")
         conn.commit()
@@ -563,10 +562,7 @@ def test_recreate_engine(monkeypatch: MonkeyPatch) -> None:
         br._recreate_engine()
         new_engine = db_mod.engine
         assert new_engine is not original_engine
-
-        os.remove(tmp_db)
     finally:
-        # Dispose the newly created engine before restoring the original
         if db_mod.engine is not original_engine:
             db_mod.engine.dispose()
         db_mod.engine = original_engine

docs/guide/using-librislog/administration.md

@@ -25,11 +25,11 @@ Click "Delete" to remove a user account. You cannot delete your own account from
 
 ### Creating a Backup
 
-Downloads the entire SQLite database as a `.db` file. This is a complete snapshot of your library, users, and settings.
+Downloads a ZIP archive containing the SQLite database, cover images, and import temp files. This is a complete snapshot of your library, users, and settings.
 
 ### Restoring a Backup
 
-Upload a previously downloaded `.db` file to restore the database. The app validates the backup before applying it.
+Upload a previously downloaded `.zip` backup file to restore the database. The app validates the backup before applying it. Backups from older versions are automatically migrated to the current schema on restore.
 
 ::: warning
 Restoring overwrites all current data. Create a fresh backup first if you want to preserve your current library.