Add SQLite WAL mode support for improved concurrent access

Enable WAL (Write-Ahead Logging) mode for SQLite databases to provide:
- Better concurrent read/write performance
- Reduced database locking errors
- Improved multi-thread/multi-process stability

Changes:
- Add event listener in LocalStorage to set PRAGMA journal_mode=WAL
- Add event listener in SessionManager.from_url() for WAL mode
- Update design.md with WAL mode documentation
- Update usage.md troubleshooting section
- Add test to verify WAL mode is enabled

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: feihoo87

docs/storage/design.md

@@ -480,6 +480,16 @@ port = 6789
 
 ## 性能考虑
 
+### SQLite WAL 模式
+
+本地存储使用 SQLite 的 WAL (Write-Ahead Logging) 模式，提供更好的并发性能：
+
+- 允许读取和写入同时进行
+- 减少数据库锁定错误
+- 提高多线程/多进程访问的稳定性
+
+WAL 模式在存储初始化时自动启用，无需额外配置。
+
 ### 写入优化
 
 - Array 使用内存缓冲区 (BUFFER_SIZE=1000)

docs/storage/usage.md

@@ -850,10 +850,12 @@ shutil.copytree(storage.base_path, backup_dir)
 
 ### 数据库锁定
 
-```python
-# 如果出现数据库锁定错误，检查是否有其他进程正在使用
+由于使用了 WAL (Write-Ahead Logging) 模式，数据库锁定问题已大大减少。WAL 模式允许读取和写入同时进行，提高了并发性能。
+
+如果出现数据库锁定错误，检查是否有其他进程正在使用：
+```bash
 # 使用 lsof 检查
-# lsof ~/.qulab/storage/storage.db
+lsof ~/.qulab/storage/storage.db
 ```
 
 ### 远程连接失败

qulab/storage/local.py

@@ -5,7 +5,7 @@
 from pathlib import Path
 from typing import TYPE_CHECKING, Iterator, List, Optional, Union
 
-from sqlalchemy import create_engine
+from sqlalchemy import create_engine, event
 from sqlalchemy.orm import sessionmaker
 
 from .base import Storage
@@ -36,6 +36,14 @@ def __init__(self, base_path: Union[str, Path], db_url: Optional[str] = None):
         self.engine = create_engine(db_url)
         self.Session = sessionmaker(bind=self.engine)
 
+        # Enable WAL mode for SQLite to improve concurrent access performance
+        @event.listens_for(self.engine, "connect")
+        def set_sqlite_wal_mode(dbapi_conn, connection_record):
+            """Enable WAL mode for SQLite database."""
+            import sqlite3
+            if isinstance(dbapi_conn, sqlite3.Connection):
+                dbapi_conn.execute("PRAGMA journal_mode=WAL")
+
         # Initialize tables
         from .models import Base
 

qulab/storage/models/base.py

@@ -23,6 +23,15 @@ def __init__(self, engine: Engine):
     def from_url(cls, url: str) -> "SessionManager":
         """Create a SessionManager from a database URL."""
         engine = create_engine(url)
+
+        # Enable WAL mode for SQLite to improve concurrent access performance
+        @event.listens_for(engine, "connect")
+        def set_sqlite_wal_mode(dbapi_conn, connection_record):
+            """Enable WAL mode for SQLite database."""
+            import sqlite3
+            if isinstance(dbapi_conn, sqlite3.Connection):
+                dbapi_conn.execute("PRAGMA journal_mode=WAL")
+
         return cls(engine)
 
     def get_session(self) -> Session:

tests/storage/test_local_storage.py

@@ -2,6 +2,7 @@
 
 import pytest
 from pathlib import Path
+from sqlalchemy import text
 
 from qulab.storage.local import LocalStorage, DocumentRef, DatasetRef
 from qulab.storage.document import Document
@@ -411,3 +412,10 @@ def test_get_latest_document(self, local_storage: LocalStorage):
         # Get latest with state filter that matches nothing
         not_found_state = local_storage.get_latest_document(name="versioned_doc", state="unknown")
         assert not_found_state is None
+
+    def test_sqlite_wal_mode_enabled(self, local_storage: LocalStorage):
+        """Test that SQLite WAL mode is enabled."""
+        with local_storage.engine.connect() as conn:
+            result = conn.execute(text("PRAGMA journal_mode"))
+            journal_mode = result.scalar()
+            assert journal_mode.lower() == "wal"