commit 2afc27c9caee1712f120a76a88c41b19e76eb859
parent 5a7c6f98077771e8ef649d3bbd97b0b912d2dc35
Author: Florian Dold <dold@taler.net>
Date: Tue, 8 Sep 2026 21:28:33 +0200
manpages: explain migration lock ownership and finalization retries
Explain that migration SQL executes on the connection holding the lock.
Document persistent finalization records and retries after schema-only
migration failures.
Diffstat:
3 files changed, 15 insertions(+), 3 deletions(-)
diff --git a/manpages/taler-auditor-dbinit.1.rst b/manpages/taler-auditor-dbinit.1.rst
@@ -38,7 +38,11 @@ Normal initialization always executes ``versioning.sql`` under the migration
lock. This script upgrades the shared ``_v`` metadata schema transactionally
and records its revision in ``_v.versioning``. An already-current script
leaves schema objects and metadata unchanged. A script with an older target
-revision preserves a newer installed revision.
+revision preserves a newer installed revision. All migration SQL runs on the
+connection holding the migration lock, so losing that connection also stops
+its writes. Pending finalization is recorded in ``_v.pending_finalizations``
+before applying migrations and cleared only when finalization commits. Failed
+finalization remains visible to ``--dry``, even without procedure files.
Its options are as follows:
diff --git a/manpages/taler-exchange-dbinit.1.rst b/manpages/taler-exchange-dbinit.1.rst
@@ -41,7 +41,11 @@ Normal initialization always executes ``versioning.sql`` under the migration
lock. This script upgrades the shared ``_v`` metadata schema transactionally
and records its revision in ``_v.versioning``. An already-current script
leaves schema objects and metadata unchanged. A script with an older target
-revision preserves a newer installed revision.
+revision preserves a newer installed revision. All migration SQL runs on the
+connection holding the migration lock, so losing that connection also stops
+its writes. Pending finalization is recorded in ``_v.pending_finalizations``
+before applying migrations and cleared only when finalization commits. Failed
+finalization remains visible to ``--dry``, even without procedure files.
Its options are as follows:
diff --git a/manpages/taler-merchant-dbinit.1.rst b/manpages/taler-merchant-dbinit.1.rst
@@ -39,7 +39,11 @@ Normal initialization always executes ``versioning.sql`` under the migration
lock. This script upgrades the shared ``_v`` metadata schema transactionally
and records its revision in ``_v.versioning``. An already-current script
leaves schema objects and metadata unchanged. A script with an older target
-revision preserves a newer installed revision.
+revision preserves a newer installed revision. All migration SQL runs on the
+connection holding the migration lock, so losing that connection also stops
+its writes. Pending finalization is recorded in ``_v.pending_finalizations``
+before applying migrations and cleared only when finalization commits. Failed
+finalization remains visible to ``--dry``, even without procedure files.
Its options are as follows:
