[Concept,2/6] patman: Enable WAL mode for concurrent database access
Commit Message
From: Simon Glass <sjg@chromium.org>
The SQLite database is opened with default settings, so a single writer
holds an exclusive lock that blocks readers, and the default busy
timeout is short enough that two patman invocations running at once
trip 'database is locked'.
Switch the connection to WAL journalling so readers and a writer can
coexist across processes, set synchronous=NORMAL (the recommended
pairing for WAL), and raise the busy timeout to 30 seconds to ride out
brief contention. Document the new behaviour in patman.rst, including
the .patman.db-wal/-shm sidecar files WAL creates so users know to
copy them together when backing the database up by hand.
Signed-off-by: Simon Glass <sjg@chromium.org>
---
tools/patman/database.py | 7 ++++++-
tools/patman/patman.rst | 10 ++++++++++
2 files changed, 16 insertions(+), 1 deletion(-)
@@ -122,8 +122,13 @@ class Database: # pylint:disable=R0904
raise ValueError('Already open')
if not os.path.exists(self.db_path):
tout.warning(f'Creating new database {self.db_path}')
- self.con = sqlite3.connect(self.db_path)
+ self.con = sqlite3.connect(self.db_path, timeout=30)
self.cur = self.con.cursor()
+ # WAL lets readers and a writer coexist across processes; the busy
+ # timeout above rides out brief contention before raising 'database
+ # is locked'
+ self.cur.execute('PRAGMA journal_mode=WAL')
+ self.cur.execute('PRAGMA synchronous=NORMAL')
self.is_open = True
def close(self):
@@ -1465,6 +1465,16 @@ Patman stores series tracking, review and workflow state in a SQLite
database (``.patman.db``) in the top-level git directory. The schema is
versioned and auto-migrated on startup (currently at v10).
+The connection is opened in WAL mode (``journal_mode=WAL``,
+``synchronous=NORMAL``) with a 30-second busy timeout, which lets multiple
+patman invocations share the database safely: concurrent readers do not block
+each other, and a writer only briefly excludes other writers. This means it is
+fine to run, for example, ``patman status`` in one terminal while a long
+``patman review`` is running in another. WAL creates ``.patman.db-wal`` and
+``.patman.db-shm`` sidecar files alongside the database; they are managed by
+SQLite and removed on a clean close, so copy or sync all three together if you
+back the database up by hand.
+
The database allows patman to track a patch series across multiple
versions, recording which patches belong to each version and how they
map to patchwork entries. This means patman can detect when a new