Merge pull request #69 from GeiserX/fix/sqlite-readonly-viewer

fix: handle read-only SQLite gracefully in viewer containers

Author: GeiserX

docker-compose.yml

@@ -155,7 +155,9 @@ services:
       LOG_LEVEL: ${LOG_LEVEL:-INFO}
 
     volumes:
-      - ./data:/data:ro
+      # SQLite needs write access for WAL journal files (.db-wal, .db-shm).
+      # Use :ro only if you are using PostgreSQL as the database backend.
+      - ./data:/data
     networks:
       - telegram-network
     # Security hardening

docs/CHANGELOG.md

@@ -6,6 +6,13 @@ For upgrade instructions, see [Upgrading](#upgrading) at the bottom.
 
 ## [Unreleased]
 
+## [6.2.6] - 2026-02-07
+
+### Fixed
+
+- **SQLite viewer crash** — Viewer container failed to start when using SQLite because `PRAGMA journal_mode=WAL` requires write access to create `.db-wal` and `.db-shm` sidecar files. WAL and `create_all` are now wrapped in try/except so the viewer degrades gracefully to default journal mode instead of crashing. (#61)
+- **Read-only volume mount** — Removed `:ro` from the viewer volume in `docker-compose.yml` since SQLite WAL needs write access. Added comment explaining when `:ro` is safe (PostgreSQL only).
+
 ## [6.2.5] - 2026-02-07
 
 ### Fixed

src/db/base.py

@@ -135,27 +135,46 @@ async def init(self) -> None:
         # via entrypoint.sh, so running create_all concurrently would race with
         # Alembic migrations and cause deadlocks.
         if self._is_sqlite:
-            async with self.engine.begin() as conn:
-                await conn.run_sync(lambda sync_conn: Base.metadata.create_all(sync_conn, checkfirst=True))
+            try:
+                async with self.engine.begin() as conn:
+                    await conn.run_sync(lambda sync_conn: Base.metadata.create_all(sync_conn, checkfirst=True))
+            except Exception as e:
+                # Viewer containers may mount the database read-only — that's fine,
+                # the backup container is responsible for creating tables.
+                logger.warning(f"Could not create/verify tables (database may be read-only): {e}")
 
         logger.info(f"Database initialized successfully ({self._db_type()})")
 
     def _setup_sqlite_pragmas(self) -> None:
-        """Set up SQLite PRAGMA settings for optimal performance."""
+        """Set up SQLite PRAGMA settings for optimal performance.
+
+        Gracefully handles read-only databases (e.g., viewer containers with
+        read-only volume mounts or non-root users without write permissions).
+        WAL mode requires write access to create .db-wal and .db-shm files;
+        if that fails the database still works in the default journal mode.
+        """
 
         @event.listens_for(self.engine.sync_engine, "connect")
         def set_sqlite_pragma(dbapi_connection, connection_record):
             cursor = dbapi_connection.cursor()
-            # WAL mode for better concurrent read/write
-            cursor.execute("PRAGMA journal_mode=WAL")
-            # 60 second busy timeout
-            cursor.execute("PRAGMA busy_timeout=60000")
-            # Faster than FULL, still safe with WAL
-            cursor.execute("PRAGMA synchronous=NORMAL")
-            # 64MB cache for better performance
-            cursor.execute("PRAGMA cache_size=-64000")
+            try:
+                # WAL mode for better concurrent read/write
+                cursor.execute("PRAGMA journal_mode=WAL")
+                # Faster than FULL, still safe with WAL
+                cursor.execute("PRAGMA synchronous=NORMAL")
+            except Exception:
+                logger.warning(
+                    "Could not enable WAL mode (database may be read-only). "
+                    "This is expected for viewer containers with read-only mounts."
+                )
+            try:
+                # 60 second busy timeout
+                cursor.execute("PRAGMA busy_timeout=60000")
+                # 64MB cache for better performance
+                cursor.execute("PRAGMA cache_size=-64000")
+            except Exception:
+                pass  # Read-only PRAGMAs are non-critical
             cursor.close()
-            logger.debug("SQLite PRAGMAs set: WAL mode, 60s timeout, 64MB cache")
 
     def _db_type(self) -> str:
         """Get human-readable database type."""