Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

fix(persistence): enable WAL, busy_timeout, and FK constraints on SQLite (#101)

Raghav Chamadiyaec2cfaeb465c
diff --git a/packages/core/src/repowise/core/persistence/database.py b/packages/core/src/repowise/core/persistence/database.py
index c29cd50b4..db92fe799 100644
--- a/packages/core/src/repowise/core/persistence/database.py
+++ b/packages/core/src/repowise/core/persistence/database.py
@@ -16,6 +16,7 @@ from collections.abc import AsyncGenerator
from contextlib import asynccontextmanager
from pathlib import Path
+from sqlalchemy import event
from sqlalchemy.ext.asyncio import (
AsyncEngine,
AsyncSession,
@@ -27,6 +28,40 @@ from sqlalchemy.sql import text
from .models import Base
+# SQLite tuning. WAL allows concurrent readers while a writer is active and
+# turns the "database is locked" failure mode into a polite block, while the
+# busy_timeout gives that block a bounded retry window before giving up.
+# Foreign keys are off by default in SQLite for legacy reasons; we want them on
+# everywhere so our FK-driven cascades behave the same in tests and production.
+_SQLITE_BUSY_TIMEOUT_MS = 5000
+
+_SQLITE_PRAGMAS: tuple[tuple[str, str], ...] = (
+ ("journal_mode", "WAL"),
+ ("synchronous", "NORMAL"),
+ ("busy_timeout", str(_SQLITE_BUSY_TIMEOUT_MS)),
+ ("foreign_keys", "ON"),
+)
+
+
+def _apply_sqlite_pragmas(dbapi_connection: object, _connection_record: object) -> None:
+ """Apply WAL, busy_timeout, and FK pragmas on every new SQLite connection.
+
+ Registered as a ``connect`` event listener so it runs once per physical
+ connection, including the first one opened after the engine is created and
+ every reconnect afterward. WAL is a database-level setting that persists in
+ the file, but we re-issue it defensively in case the file was created by an
+ older repowise version, by ``alembic``, or by a third-party tool that left
+ journal_mode at the default ``delete``.
+ """
+ cursor = dbapi_connection.cursor() # type: ignore[attr-defined]
+ try:
+ for name, value in _SQLITE_PRAGMAS:
+ # journal_mode returns the new mode and must be queried, not assigned,
+ # because in :memory: databases it silently downgrades to MEMORY.
+ cursor.execute(f"PRAGMA {name}={value}")
+ finally:
+ cursor.close()
+
__all__ = [
"AsyncEngine",
"AsyncSession",
@@ -144,7 +179,12 @@ def create_engine(
# PostgreSQL — asyncpg handles its own connection pool
kwargs["pool_pre_ping"] = True
- return create_async_engine(db_url, **kwargs)
+ engine = create_async_engine(db_url, **kwargs)
+ if is_sqlite:
+ # The ``connect`` event fires for the underlying DBAPI connection, so we
+ # listen on the sync engine that backs the AsyncEngine.
+ event.listen(engine.sync_engine, "connect", _apply_sqlite_pragmas)
+ return engine
def create_session_factory(engine: AsyncEngine) -> async_sessionmaker[AsyncSession]:
diff --git a/tests/unit/persistence/test_database_pragmas.py b/tests/unit/persistence/test_database_pragmas.py
new file mode 100644
index 000000000..839f5b46e
--- /dev/null
+++ b/tests/unit/persistence/test_database_pragmas.py
@@ -0,0 +1,111 @@
+"""Verify that file-backed SQLite engines come up with WAL, busy_timeout, and FK
+constraints enabled. These are the settings that make concurrent
+``repowise update`` invocations on the same workspace stop colliding (issue #95).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import sqlite3
+from pathlib import Path
+
+import pytest
+from sqlalchemy import text
+
+from repowise.core.persistence import create_engine, init_db
+
+
+async def _read_pragma(engine, pragma: str) -> str:
+ async with engine.connect() as conn:
+ result = await conn.execute(text(f"PRAGMA {pragma}"))
+ row = result.fetchone()
+ return str(row[0]) if row is not None else ""
+
+
+async def test_file_sqlite_engine_uses_wal(tmp_path: Path) -> None:
+ db_url = f"sqlite+aiosqlite:///{tmp_path / 'wiki.db'}"
+ engine = create_engine(db_url)
+ try:
+ await init_db(engine)
+ mode = await _read_pragma(engine, "journal_mode")
+ assert mode.lower() == "wal"
+ finally:
+ await engine.dispose()
+
+
+async def test_file_sqlite_engine_sets_busy_timeout(tmp_path: Path) -> None:
+ db_url = f"sqlite+aiosqlite:///{tmp_path / 'wiki.db'}"
+ engine = create_engine(db_url)
+ try:
+ await init_db(engine)
+ timeout = await _read_pragma(engine, "busy_timeout")
+ assert int(timeout) >= 1000
+ finally:
+ await engine.dispose()
+
+
+async def test_file_sqlite_engine_enforces_foreign_keys(tmp_path: Path) -> None:
+ db_url = f"sqlite+aiosqlite:///{tmp_path / 'wiki.db'}"
+ engine = create_engine(db_url)
+ try:
+ await init_db(engine)
+ fk = await _read_pragma(engine, "foreign_keys")
+ assert int(fk) == 1
+ finally:
+ await engine.dispose()
+
+
+async def test_concurrent_writers_do_not_lock(tmp_path: Path) -> None:
+ """Two concurrent writers against the same file-backed SQLite database
+ should both succeed once WAL plus busy_timeout are active. Without the fix
+ this raises ``sqlite3.OperationalError: database is locked``."""
+
+ db_path = tmp_path / "wiki.db"
+ db_url = f"sqlite+aiosqlite:///{db_path}"
+ engine = create_engine(db_url)
+ try:
+ await init_db(engine)
+ # Seed one row so the second writer has something to update.
+ async with engine.begin() as conn:
+ await conn.execute(text("CREATE TABLE IF NOT EXISTS t (k INTEGER PRIMARY KEY, v INTEGER)"))
+ await conn.execute(text("INSERT INTO t (k, v) VALUES (1, 0)"))
+ finally:
+ await engine.dispose()
+
+ async def write_in_own_engine(value: int) -> None:
+ own = create_engine(db_url)
+ try:
+ async with own.begin() as conn:
+ await conn.execute(text("UPDATE t SET v = :v WHERE k = 1"), {"v": value})
+ finally:
+ await own.dispose()
+
+ # Without WAL plus busy_timeout one of these would raise OperationalError.
+ await asyncio.gather(write_in_own_engine(1), write_in_own_engine(2))
+
+
+def test_pragmas_survive_a_fresh_sync_open(tmp_path: Path) -> None:
+ """After the async engine creates the database, opening it through the raw
+ sqlite3 driver should still report WAL because journal_mode is a persistent
+ file-level setting."""
+
+ async def _create() -> Path:
+ db_path = tmp_path / "wiki.db"
+ engine = create_engine(f"sqlite+aiosqlite:///{db_path}")
+ try:
+ await init_db(engine)
+ finally:
+ await engine.dispose()
+ return db_path
+
+ db_path = asyncio.run(_create())
+ conn = sqlite3.connect(db_path)
+ try:
+ mode = conn.execute("PRAGMA journal_mode").fetchone()[0]
+ assert mode.lower() == "wal"
+ finally:
+ conn.close()