From 195045d2576df66ac82a7391bd8f27f4345ede4e Mon Sep 17 00:00:00 2001 From: Simon Pinfold Date: Wed, 16 Sep 2026 17:14:42 -0700 Subject: [PATCH] docs(db): restore the rationale for locking before migration Commit 1dbcdcd7 and the comment-cleanup pass 8205022f reduced this to "All database reads and writes, including the legacy import, run under the lock", dropping the part that did the work: upstream master locks after migrating and justifies it with "Alembic uses its own connection, so we must wait until it's done before locking -- otherwise our own lock blocks the migration". That is false, the lock is on a separate .lock file, and the surviving sentence said nothing to stop a contributor "fixing" the ordering back. Restored and adapted rather than pasted: the legacy copy and the db_exists probe now happen inside the lock, which the original text predates, so both are named in the list of things the ordering makes mutually exclusive. --- app/database/db.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/app/database/db.py b/app/database/db.py index ca18b97c0..cd684e337 100644 --- a/app/database/db.py +++ b/app/database/db.py @@ -182,7 +182,11 @@ def _init_file_db(db_url): db_path = get_db_path() prepare_file_db_path(db_path) - # All database reads and writes, including the legacy import, run under the lock. + # Lock BEFORE any of the work below — deliberately diverging from upstream master, whose + # "it would block Alembic" rationale is false (the lock guards a separate `.lock` file, + # not the database Alembic connects to). Only this order makes the legacy import, the + # existence probe deciding whether a backup is taken, revision inspection, backup, upgrade + # and the failure-path restore mutually exclusive between processes. _acquire_file_lock(db_path) try: copy_legacy_default_db(db_path)